flutter_3d_controller

颤振 3D 控制器

最完整的 Flutter 包，用于渲染各种格式的交互式 3D 模型（ GLB 、 GLTF 、 OBJ 、 FBX ），并且能够控制动画、纹理、相机等。

为什么选择 Flutter 3D 控制器？

Flutter 3D 控制器包是用于渲染各种 3D 模型格式的最全面的解决方案，提供广泛的功能，使用户能够对 3D 模型进行最佳控制。

它在实现新功能方面处于领先地位，而其他一些软件包只是复制了 Flutter 3D Controller 的功能和代码，没有适当的信用或遵守许可。

值得注意的是，在测试其他可用软件包时，用户可能会在 iOS 和某些 Android 设备上遇到手势故障。然而， Flutter 3D Controller是第一个也是唯一一个通过手势拦截器功能解决此问题的软件包，该功能在2024 年 10 月 5 日发布的2.0.0 版本中引入。

特征

• 移动和网页稳定版（支持glb 、 gltf和obj格式）
• 从资产加载 3D 模型
• 从 URL 加载 3D 模型
• 手势拦截器（防止手势识别器发生故障）
• 控制器模型加载值监听器
• 模型加载状态回调、 onProgress 、 onLoad和onError
• 加载带有纹理和mtl文件的obj 3D 模型
• obj 3D 模型的比例和相机属性
• 播放动画
• 动画之间切换
• 暂停动画
• 重置动画
• 停止动画
• 获取可用的动画列表
• 纹理之间切换
• 获取可用纹理列表
• 设置相机目标
• 重置相机目标
• 设置相机轨道
• 重置相机轨道
• 默认加载进度条颜色
• 启用/禁用触摸控制

样品

兼容性

• 安卓
• iOS系统
• 网络

笔记

• 目前该软件包支持GLB 、 glTF和OBJ格式，其他 3D 格式即将推出。
• 访问完整示例以了解如何使用此包。

简短的例子

控制器使用方法

 //Create controller object to control 3D model.
Flutter3DController controller = Flutter3DController ();

//Listen to model loading state via controller
controller.onModelLoaded. addListener (() {
  debugPrint ( 'model is loaded : ${ controller . onModelLoaded . value }' );
});

//It will play 3D model animation, you can use it to play or switch between animations.
controller. playAnimation ();

//If you pass specific animation name it will play that specific animation.
//If you pass null and your model has at least 1 animation it will play first animation.
controller. playAnimation (animationName : chosenAnimation);

//It will pause the animation at current frame.
controller. pauseAnimation ();

//It will reset and play animation from first frame (from beginning).
controller. resetAnimation ();

//It will stop the animation.
controller. stopAnimation ();

//It will return available animation list of 3D model.
await controller. getAvailableAnimations ();

//It will load desired texture of 3D model, you need to pass texture name.
controller. setTexture (textureName : chosenTexture);

//It will return available textures list of 3D model.
await controller. getAvailableTextures ();

//It will set your desired camera target.
controller. setCameraTarget ( 0.3 , 0.2 , 0.4 );

//It will reset the camera target to default.
controller. resetCameraTarget ();

//It will set your desired camera orbit.
controller. setCameraOrbit ( 20 , 20 , 5 );

//It will reset the camera orbit to default.
controller. resetCameraOrbit ();

如何加载 glb 和 gltf 模型

 //The 3D viewer widget for glb and gltf format
Flutter3DViewer (
    //If you pass 'true' the flutter_3d_controller will add gesture interceptor layer
    //to prevent gesture recognizers from malfunctioning on iOS and some Android devices.
    //the default value is true
    activeGestureInterceptor : true ,
    //If you don't pass progressBarColor, the color of defaultLoadingProgressBar will be grey.
    //You can set your custom color or use [Colors.transparent] for hiding loadingProgressBar.
    progressBarColor : Colors .orange,
    //You can disable viewer touch response by setting 'enableTouch' to 'false'
    enableTouch : true ,
    //This callBack will return the loading progress value between 0 and 1.0
    onProgress : ( double progressValue) {
      debugPrint ( 'model loading progress : $ progressValue ' );
    },
    //This callBack will call after model loaded successfully and will return model address
    onLoad : ( String modelAddress) {
      debugPrint ( 'model loaded : $ modelAddress ' );
    },
    //this callBack will call when model failed to load and will return failure error
    onError : ( String error) {
      debugPrint ( 'model failed to load : $ error ' );
    },
    //You can have full control of 3d model animations, textures and camera
    controller : controller,
    src : 'assets/business_man.glb' , //3D model with different animations
    //src: 'assets/sheen_chair.glb', //3D model with different textures
    //src: 'https://modelviewer.dev/shared-assets/models/Astronaut.glb', // 3D model from URL
)

如何加载 obj 模型

 //The 3D viewer widget for obj format
Flutter3DViewer . obj (
    src : 'assets/flutter_dash.obj' ,
    //src: 'https://raw.githubusercontent.com/m-r-davari/content-holder/refs/heads/master/flutter_3d_controller/flutter_dash_model/flutter_dash.obj',
    scale : 5 ,
    // Initial scale of obj model
    cameraX : 0 ,
    // Initial cameraX position of obj model
    cameraY : 0 ,
    //Initial cameraY position of obj model
    cameraZ : 10 ,
    //Initial cameraZ position of obj model
    //This callBack will return the loading progress value between 0 and 1.0
    onProgress : ( double progressValue) {
      debugPrint ( 'model loading progress : $ progressValue ' );
    },
    //This callBack will call after model loaded successfully and will return model address
    onLoad : ( String modelAddress) {
      debugPrint ( 'model loaded : $ modelAddress ' );
    },
    //this callBack will call when model failed to load and will return failure erro
    onError : ( String error) {
      debugPrint ( 'model failed to load : $ error ' );
    },
)

安装

pubspec.yaml

 dependencies :
  flutter_3d_controller : ^2.0.2

AndroidManifest.xml （仅限 Android）

配置应用程序的android/app/src/main/AndroidManifest.xml如下所示：

+ android:label="example" + android:usesCleartextTraffic="true">

 +   

     -       android:label="example">
+       android:label="example"
+       android:usesCleartextTraffic="true">
        

app/build.gradle （仅限 Android）

将 minSdkVersion 更改为 21。

 defaultConfig {
    ...
    minSdkVersion 21
    ...
}

Info.plist （仅限 iOS）

要在 iOS 上使用此包，您需要通过向应用程序的ios/Runner/Info.plist文件添加一个布尔属性来选择嵌入视图预览，其中键为io.flutter.embedded_views_preview ，值为YES ：

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

web/index.html （仅限网页）

修改web/index.html的标签来加载 JavaScript，如下所示：

">

 < head >
  
    < script type =" module " src =" ./assets/packages/flutter_3d_controller/assets/model_viewer.min.js " defer >  script >
 head > 

常见问题解答

• 3D模型无法加载：首先检查示例，如果示例中的模型加载，可能是您的模型或模型路径有问题。
• 无法检索动画列表：检查动画名称中是否存在可能导致 JSON 编码错误的特殊字符。
• 无法从 url 加载 3D 模型：可能是由于 [CORS] 安全限制。托管模型文件的服务器必须发送适当的 CORS 响应标头，以便查看器能够加载该文件。请参阅 google/model-viewer#1015

无法在真实的 iOS 设备上使用 url？

问题描述：如果您在真实 iOS 设备上从 URL 加载 3D 模型时遇到问题，锁定模式可能是原因。锁定模式是 iOS 中的一项安全功能，可限制某些功能（例如网络请求或加载嵌入内容）以保护用户数据。

如何禁用锁定模式

请按照以下步骤在您的设备上禁用锁定模式：

1. 打开 iPhone 上的“设置”应用。
2. 向下滚动并选择隐私和安全。
3. 点击锁定模式。
4. 选择关闭锁定模式。您可能需要输入密码进行确认。
5. 禁用锁定模式后，返回应用程序并尝试再次加载 3D 模型。

---

更多信息

该软件包使用 Google 的模型查看器来渲染 3D 模型，在渲染某些模型/纹理时可能会出现一些问题，软件包的核心（模型查看器）将来将会更改以支持所有类型的 3D 模型。