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 模型。