콘텐츠 대표 이미지 - Flutter AR 뷰어 개발: ar_flutter_plugin으로 증강현실 앱 구현하기
📱 모바일/앱 개발

Flutter AR 뷰어 개발: ar_flutter_plugin으로 증강현실 앱 구현하기

🚀 Flutter + AR = 미래의 앱 개발! ar_flutter_plugin의 모든 것을 친구처럼 파헤쳐보자

Flutter AR ar_flutter_plugin ARCore ARKit 3D 모델 모바일 앱
Flutter AR 뷰어 ar_flutter_plugin 활용 가이드 📱 🔮 🧊 ARCore / ARKit 3D 모델 렌더링 크로스 플랫폼
🌟

AR이 뭔데? 왜 Flutter로 만들어?

야, 솔직히 말해보자. 요즘 스마트폰 들고 카메라 켜면 뭔가 신기한 게 화면에 떠오르는 거 본 적 있지? 이케아 앱에서 소파를 내 방에 가상으로 배치해보거나, 포켓몬 GO에서 포켓몬이 현실 공간에 나타나는 것처럼 말이야. 그게 바로 AR(Augmented Reality, 증강현실)이야! 🔮

그런데 이걸 Flutter로 만들 수 있다고? 응, 맞아. 그것도 꽤 쉽게! 오늘 우리가 파헤칠 주인공은 바로 ar_flutter_plugin이라는 패키지야. 이 친구 덕분에 Flutter 개발자들이 iOS와 Android 양쪽에서 동시에 AR 기능을 구현할 수 있게 됐거든.

💡 이 글에서 배울 것들 AR의 기본 개념부터 시작해서, ar_flutter_plugin 설치 및 설정, 3D 모델 배치, 평면 감지, 앵커 시스템, 실제 프로젝트 구현까지 — 처음 AR 개발을 시작하는 사람도 따라올 수 있게 차근차근 설명할게!

Flutter를 어느 정도 써본 사람이라면 이 글이 훨씬 재미있을 거야. 근데 Flutter 초보여도 걱정 마. 핵심 개념 위주로 설명할 테니까 충분히 따라올 수 있어. 자, 그럼 AR의 세계로 다이브해보자! 🚀


📚

AR 개발의 기초: ARCore와 ARKit을 알아야 해

ar_flutter_plugin을 제대로 쓰려면 그 밑에서 돌아가는 엔진들을 알아야 해. Flutter AR 개발의 핵심은 두 가지 플랫폼 네이티브 AR 프레임워크야.

Google ARCore (Android)

ARCore는 Google이 만든 Android용 AR 플랫폼이야. 2018년에 정식 출시됐고, 지금은 수억 대의 Android 기기를 지원해. ARCore가 하는 일을 쉽게 설명하면:

🔍 ARCore의 핵심 기능 3가지 1. 모션 트래킹 (Motion Tracking)
폰이 공간에서 어디에 있는지 실시간으로 파악해. 카메라 이미지와 IMU(관성 측정 장치) 데이터를 결합해서 폰의 위치와 방향을 추적하지. 이걸 Visual Inertial Odometry(VIO)라고 불러.

2. 환경 이해 (Environmental Understanding)
바닥, 테이블, 벽 같은 수평/수직 평면을 감지해. 이 평면 위에 3D 오브젝트를 올려놓을 수 있어.

3. 조명 추정 (Light Estimation)
현재 환경의 조명 조건을 분석해서 AR 오브젝트에 자연스러운 그림자와 반사를 적용해줘. 덕분에 가상 물체가 현실에 있는 것처럼 보여.

Apple ARKit (iOS)

ARKit은 Apple이 2017년 iOS 11과 함께 발표한 iOS용 AR 프레임워크야. ARCore와 비슷한 기능을 제공하지만 Apple 생태계에 최적화되어 있어.

🍎 ARKit의 특징적인 기능들 LiDAR 스캐너 지원: iPhone 12 Pro 이후 모델에는 LiDAR 센서가 달려있어. 이걸 활용하면 공간을 훨씬 정밀하게 스캔할 수 있어. 어두운 환경에서도 평면 감지가 잘 돼.

Face Tracking: TrueDepth 카메라를 이용해서 얼굴을 3D로 추적해. 스냅챗 필터 같은 거 만들 때 쓰는 기술이야.

Reality Composer 연동: Apple의 Reality Composer 툴로 만든 AR 씬을 바로 불러올 수 있어.

그래서 ar_flutter_plugin이 뭐야?

자, 이제 핵심이야. ar_flutter_plugin은 Flutter에서 ARCore(Android)와 ARKit(iOS)를 하나의 통합된 API로 사용할 수 있게 해주는 패키지야. 즉, 코드 한 번 짜면 iOS, Android 양쪽에서 AR이 돌아간다는 거지!

ar_flutter_plugin의 공식 GitHub: https://github.com/CariusLars/ar_flutter_plugin
개발자: Lars Carius
라이선스: MIT
지원 플랫폼: Android (ARCore), iOS (ARKit)

이 플러그인은 SceneView라는 위젯을 중심으로 동작해. Flutter 위젯 트리에 ARView를 넣으면, 그 안에서 카메라 피드가 나오고 AR 기능이 활성화되는 구조야.

AR 플랫폼 비교 ARCore Google · Android 📍 모션 트래킹 🗺️ 평면 감지 💡 조명 추정 ☁️ Cloud Anchors 🌐 Geospatial API Android 7.0+ 지원 수억 대 기기 호환 ARKit Apple · iOS 📍 모션 트래킹 🗺️ 평면 감지 💡 조명 추정 🔭 LiDAR 지원 😊 Face Tracking iOS 11+ 지원 Apple 기기 최적화 ar_flutter_plugin Flutter 통합 레이어 ✅ 단일 코드베이스 ✅ 크로스 플랫폼 ✅ 통합 API

⚙️

ar_flutter_plugin 설치 및 프로젝트 설정

자, 이제 진짜 코드를 써볼 시간이야! 설치 과정이 좀 길긴 한데, 한 번만 제대로 해두면 나중에 편해. 차근차근 따라와봐. 😊

Step 1: pubspec.yaml에 의존성 추가

Flutter 프로젝트의 pubspec.yaml 파일에 ar_flutter_plugin을 추가해야 해.

# pubspec.yaml
dependencies:
  flutter:
    sdk: flutter
  ar_flutter_plugin: ^0.7.3   # 최신 버전 확인 후 사용
  vector_math: ^2.1.4          # 3D 수학 연산용
⚠️ 버전 주의! ar_flutter_plugin은 활발히 업데이트되고 있어. pub.dev에서 최신 버전을 꼭 확인하고 사용해. 2024년 기준으로 0.7.x 버전대가 안정적으로 사용되고 있어.

Step 2: Android 설정

Android에서 ARCore를 사용하려면 몇 가지 설정이 필요해.

android/app/build.gradle 수정:

android {
    compileSdkVersion 33
    
    defaultConfig {
        minSdkVersion 24  // ARCore는 최소 API 24 필요!
        targetSdkVersion 33
    }
}

dependencies {
    implementation 'com.google.ar:core:1.38.0'
}

android/app/src/main/AndroidManifest.xml 수정:

<manifest ...>
    <!-- 카메라 권한 필수! -->
    <uses-permission android:name="android.permission.CAMERA"/>
    
    <!-- ARCore 필수 또는 선택적 사용 선언 -->
    <uses-feature android:name="android.hardware.camera.ar" 
                  android:required="true"/>
    
    <application ...>
        <!-- ARCore 메타데이터 -->
        <meta-data 
            android:name="com.google.ar.core" 
            android:value="required"/>
        <!-- required: ARCore 없으면 앱 설치 불가 -->
        <!-- optional: ARCore 없어도 앱 설치 가능 -->
    </application>
</manifest>
💡 required vs optional android:value="required"로 설정하면 ARCore가 지원되지 않는 기기에서는 Play Store에서 앱이 아예 안 보여. AR이 앱의 핵심 기능이라면 required, 부가 기능이라면 optional을 써.

Step 3: iOS 설정

iOS에서는 ARKit 설정이 필요해. ios/Runner/Info.plist에 카메라 권한을 추가해야 해.

<!-- ios/Runner/Info.plist -->
<dict>
    ...
    <key>NSCameraUsageDescription</key>
    <string>AR 기능을 사용하기 위해 카메라 접근이 필요합니다</string>
    
    <key>io.flutter.embedded_views_preview</key>
    <true/>
    ...
</dict>

ios/Podfile 설정:

# ios/Podfile
platform :ios, '12.0'  # ARKit은 iOS 11+, 안정성을 위해 12.0 권장

# 중요: use_frameworks! 설정
use_frameworks!

Step 4: 의존성 설치

# Flutter 패키지 설치
flutter pub get

# iOS CocoaPods 설치 (iOS 개발 시)
cd ios && pod install && cd ..
🎉 설정 완료! 이제 실제 AR 코드를 작성할 준비가 됐어. 설정이 좀 복잡해 보이지만, 이건 네이티브 AR 프레임워크를 연결하는 과정이라 어쩔 수 없어. 한 번만 하면 돼!

🔨

기본 AR 뷰어 구현: 첫 번째 AR 앱 만들기

설정이 끝났으면 이제 진짜 재미있는 부분이야! 기본적인 AR 뷰어를 만들어보자. 화면에 카메라가 켜지고, 바닥을 인식하고, 3D 오브젝트를 올려놓는 기능을 구현할 거야.

ARView 위젯의 기본 구조

ar_flutter_plugin의 핵심 위젯은 ARView야. 이 위젯이 카메라 피드를 보여주고 AR 기능을 활성화해줘.

import 'package:flutter/material.dart';
import 'package:ar_flutter_plugin/ar_flutter_plugin.dart';
import 'package:ar_flutter_plugin/datatypes/config_planedetection.dart';
import 'package:ar_flutter_plugin/datatypes/node_types.dart';
import 'package:ar_flutter_plugin/datatypes/hittest_result_types.dart';
import 'package:ar_flutter_plugin/managers/ar_anchor_manager.dart';
import 'package:ar_flutter_plugin/managers/ar_location_manager.dart';
import 'package:ar_flutter_plugin/managers/ar_object_manager.dart';
import 'package:ar_flutter_plugin/managers/ar_session_manager.dart';
import 'package:ar_flutter_plugin/models/ar_anchor.dart';
import 'package:ar_flutter_plugin/models/ar_node.dart';
import 'package:ar_flutter_plugin/models/ar_hittest_result.dart';
import 'package:vector_math/vector_math_64.dart';

class BasicARViewer extends StatefulWidget {
  const BasicARViewer({Key? key}) : super(key: key);

  @override
  State<BasicARViewer> createState() => _BasicARViewerState();
}

class _BasicARViewerState extends State<BasicARViewer> {
  // AR 매니저들 - 각각 다른 역할을 담당해
  ARSessionManager? arSessionManager;
  ARObjectManager? arObjectManager;
  ARAnchorManager? arAnchorManager;
  
  // 배치된 노드와 앵커를 추적하기 위한 리스트
  List<ARNode> nodes = [];
  List<ARAnchor> anchors = [];

  @override
  void dispose() {
    // 메모리 누수 방지를 위해 세션 종료
    arSessionManager!.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('AR 뷰어'),
        backgroundColor: Colors.transparent,
        elevation: 0,
      ),
      body: Stack(
        children: [
          // AR 뷰 - 화면 전체를 차지
          ARView(
            onARViewCreated: onARViewCreated,
            planeDetectionConfig: PlaneDetectionConfig.horizontalAndVertical,
          ),
          // 하단 버튼 오버레이
          Align(
            alignment: Alignment.bottomCenter,
            child: Padding(
              padding: const EdgeInsets.only(bottom: 30),
              child: ElevatedButton.icon(
                onPressed: removeAllObjects,
                icon: const Icon(Icons.delete),
                label: const Text('모두 지우기'),
                style: ElevatedButton.styleFrom(
                  backgroundColor: Colors.red.withOpacity(0.8),
                ),
              ),
            ),
          ),
        ],
      ),
    );
  }
  
  // AR 뷰가 생성될 때 호출되는 콜백
  void onARViewCreated(
    ARSessionManager sessionManager,
    ARObjectManager objectManager,
    ARAnchorManager anchorManager,
    ARLocationManager locationManager,
  ) {
    arSessionManager = sessionManager;
    arObjectManager = objectManager;
    arAnchorManager = anchorManager;

    // 세션 초기화
    arSessionManager!.onInitialize(
      showFeaturePoints: false,  // 특징점 표시 여부
      showPlanes: true,          // 감지된 평면 표시
      customPlaneTexturePath: null,
      showWorldOrigin: false,    // 월드 원점 표시 여부
      handleTaps: true,          // 탭 이벤트 처리
    );
    
    // 오브젝트 매니저 초기화
    arObjectManager!.onInitialize();
    
    // 탭 이벤트 핸들러 등록
    arSessionManager!.onPlaneOrPointTap = onPlaneOrPointTapped;
  }
  
  // 평면이나 포인트를 탭했을 때 호출
  Future<void> onPlaneOrPointTapped(
    List<ARHitTestResult> hitTestResults,
  ) async {
    // 첫 번째 히트 결과 사용
    var singleHitTestResult = hitTestResults.firstWhere(
      (hitTestResult) => hitTestResult.type == ARHitTestResultType.plane,
      orElse: () => hitTestResults.first,
    );
    
    // 앵커 생성 (현실 공간의 고정점)
    var newAnchor = ARPlaneAnchor(
      transformation: singleHitTestResult.worldTransform,
    );
    bool? didAddAnchor = await arAnchorManager!.addAnchor(newAnchor);
    
    if (didAddAnchor!) {
      anchors.add(newAnchor);
      
      // 노드 생성 (3D 오브젝트)
      var newNode = ARNode(
        type: NodeType.webGLB,  // GLB 형식의 3D 모델
        uri: "https://github.com/KhronosGroup/glTF-Sample-Models/raw/master/2.0/Duck/glTF-Binary/Duck.glb",
        scale: Vector3(0.2, 0.2, 0.2),  // 크기 조절
        position: Vector3(0.0, 0.0, 0.0),
        rotation: Vector4(1.0, 0.0, 0.0, 0.0),
      );
      
      bool? didAddNodeToAnchor = await arObjectManager!.addNode(
        newNode,
        planeAnchor: newAnchor,
      );
      
      if (didAddNodeToAnchor!) {
        nodes.add(newNode);
      }
    }
  }
  
  // 모든 오브젝트 제거
  Future<void> removeAllObjects() async {
    for (var node in nodes) {
      await arObjectManager!.removeNode(node);
    }
    for (var anchor in anchors) {
      await arAnchorManager!.removeAnchor(anchor);
    }
    nodes.clear();
    anchors.clear();
  }
}
💡 코드 핵심 포인트! 위 코드에서 가장 중요한 개념은 앵커(Anchor)와 노드(Node)의 관계야.
- 앵커: 현실 공간의 특정 위치에 고정된 "핀" 같은 거야. 폰이 움직여도 이 위치는 유지돼.
- 노드: 앵커에 붙어있는 3D 오브젝트야. 앵커가 있어야 노드를 배치할 수 있어.

ARView의 주요 파라미터들

파라미터 타입 설명
onARViewCreated Function AR 뷰 초기화 완료 시 호출되는 콜백
planeDetectionConfig PlaneDetectionConfig 평면 감지 설정 (수평, 수직, 둘 다)
showFeaturePoints bool ARCore/ARKit 특징점 시각화 여부
showPlanes bool 감지된 평면 시각화 여부
showWorldOrigin bool 월드 좌표계 원점 표시 여부
handleTaps bool 탭 이벤트 처리 활성화 여부

🎛️

ar_flutter_plugin의 매니저 시스템 파헤치기

ar_flutter_plugin의 아키텍처를 이해하려면 매니저 시스템을 알아야 해. 이 플러그인은 기능별로 역할을 분리한 4개의 매니저로 구성되어 있어. 각각 어떤 일을 하는지 자세히 살펴보자!

1. ARSessionManager - AR 세션의 총사령관 🎯

ARSessionManager는 AR 세션 전체를 관리하는 핵심 매니저야. AR 세션의 시작, 종료, 설정을 담당해.

// ARSessionManager 주요 메서드들

// 세션 초기화
arSessionManager!.onInitialize(
  showFeaturePoints: true,   // 특징점(노란 점들) 표시
  showPlanes: true,          // 평면 표시
  showWorldOrigin: true,     // 좌표축 표시
  handleTaps: true,          // 탭 처리
  handlePans: true,          // 팬(드래그) 처리
  handleRotation: true,      // 회전 처리
);

// 스크린샷 찍기
Uint8List? screenshot = await arSessionManager!.snapshot();

// 탭 이벤트 핸들러
arSessionManager!.onPlaneOrPointTap = (hitResults) {
  // 탭한 위치의 AR 히트 테스트 결과 처리
};

// 에러 핸들러
arSessionManager!.onError = (errorMessage) {
  print("AR 에러: $errorMessage");
};

// 세션 종료 (dispose에서 반드시 호출!)
arSessionManager!.dispose();

2. ARObjectManager - 3D 오브젝트 관리자 🧊

ARObjectManager는 AR 씬에 3D 오브젝트(노드)를 추가하고 제거하는 역할을 해. 가장 자주 사용하게 될 매니저야.

// ARObjectManager 주요 메서드들

// 노드 추가 (앵커에 붙이기)
ARNode newNode = ARNode(
  type: NodeType.webGLB,
  uri: "https://example.com/model.glb",
  scale: Vector3(0.3, 0.3, 0.3),
  position: Vector3(0.0, 0.0, 0.0),
  rotation: Vector4(1.0, 0.0, 0.0, 0.0),
  name: "myNode",  // 노드 식별자
);

bool? success = await arObjectManager!.addNode(
  newNode,
  planeAnchor: anchor,  // 앵커에 붙이기
);

// 노드 제거
await arObjectManager!.removeNode(node);

// 노드 변환 (위치, 회전, 크기 변경)
await arObjectManager!.transformationChanged(node);

// 탭 이벤트 핸들러
arObjectManager!.onNodeTap = (tappedNodes) {
  print("탭된 노드: ${tappedNodes.first}");
};

// 팬(드래그) 이벤트 핸들러
arObjectManager!.onPanStart = (nodeName) {
  print("드래그 시작: $nodeName");
};

arObjectManager!.onPanChange = (nodeName) {
  print("드래그 중: $nodeName");
};

arObjectManager!.onPanEnd = (nodeName, transform) {
  print("드래그 종료: $nodeName");
};

3. ARAnchorManager - 앵커 관리자 ⚓

ARAnchorManager는 AR 앵커를 관리해. 앵커는 현실 공간의 특정 위치에 고정된 기준점이야.

// ARAnchorManager 주요 메서드들

// 평면 앵커 생성
ARPlaneAnchor planeAnchor = ARPlaneAnchor(
  transformation: hitTestResult.worldTransform,
);
bool? added = await arAnchorManager!.addAnchor(planeAnchor);

// 앵커 제거
await arAnchorManager!.removeAnchor(anchor);

// Cloud Anchor 업로드 (다른 기기와 공유 가능!)
// ARCore Cloud Anchors API 필요
arAnchorManager!.onAnchorUploaded = (anchor) {
  // 클라우드에 앵커 업로드 완료
  print("클라우드 앵커 ID: ${anchor.cloudanchorid}");
};

arAnchorManager!.onAnchorDownloaded = (anchor) {
  // 클라우드 앵커 다운로드 완료
};

4. ARLocationManager - 위치 기반 AR 관리자 📍

ARLocationManager는 GPS 위치 정보를 AR과 연동할 때 사용해. 지오스페이셜 AR(실제 지리 좌표 기반 AR)을 구현할 때 필요해.

// ARLocationManager 사용 예시
arLocationManager.startLocationUpdates();

arLocationManager.onLocationUpdated = (location) {
  print("현재 위치: ${location.latitude}, ${location.longitude}");
  print("고도: ${location.altitude}");
};

arLocationManager.stopLocationUpdates();
🏗️ 매니저 시스템의 장점 각 기능이 독립된 매니저로 분리되어 있어서 코드 관리가 훨씬 쉬워. 필요한 기능만 골라서 쓸 수 있고, 각 매니저의 책임이 명확해서 디버깅도 편해. 이런 설계 패턴을 관심사 분리(Separation of Concerns)라고 해.
ar_flutter_plugin 매니저 아키텍처 ARView 위젯 Flutter UI 레이어 onARViewCreated 콜백 4개의 매니저 인스턴스 전달 ARSession Manager 세션 초기화/종료 스크린샷 탭 이벤트 ARObject Manager 3D 노드 추가/제거 변환 처리 드래그/회전 ARAnchor Manager 앵커 생성/제거 Cloud Anchors 공간 고정점 ARLocation Manager GPS 위치 연동 지오스페이셜 AR 위치 업데이트

🧊

3D 모델 형식과 NodeType 이해하기

AR 앱에서 3D 오브젝트를 표시하려면 3D 모델 파일이 필요해. ar_flutter_plugin은 여러 가지 3D 모델 형식과 소스를 지원해. 어떤 형식을 써야 할지 헷갈릴 수 있으니 정리해줄게!

NodeType 종류

NodeType 설명 사용 예시
NodeType.webGLB 웹 URL에서 GLB 파일 로드 CDN에 올린 3D 모델
NodeType.localGLTF2 앱 assets에서 GLTF/GLB 로드 앱 번들에 포함된 모델
NodeType.fileSystemAppFolderGLB 앱 파일시스템에서 GLB 로드 다운로드한 모델
NodeType.fileSystemAppFolderGLTF2 앱 파일시스템에서 GLTF 로드 다운로드한 GLTF 모델

GLB vs GLTF - 뭐가 다른 거야?

🔷 GLTF (GL Transmission Format) - JSON 기반의 3D 모델 형식이야
- .gltf 파일 + .bin 파일 + 텍스처 이미지 파일들로 구성돼
- 여러 파일로 분리되어 있어서 개별 파일 수정이 가능해
- 웹 표준 3D 형식으로 Khronos Group이 개발했어

🔶 GLB (GL Binary)
- GLTF의 바이너리 버전이야
- 모든 데이터(메시, 텍스처, 애니메이션)가 하나의 .glb 파일에 담겨
- 파일 하나만 관리하면 되니까 배포가 훨씬 편해
- AR 앱에서는 GLB를 주로 사용해!

로컬 에셋 3D 모델 사용하기

앱에 3D 모델을 번들로 포함시키려면 pubspec.yaml에 에셋을 등록해야 해.

# pubspec.yaml
flutter:
  assets:
    - assets/models/
    - assets/models/duck.glb
    - assets/models/chair.glb
// 로컬 에셋 모델 사용
ARNode localNode = ARNode(
  type: NodeType.localGLTF2,
  uri: "assets/models/duck.glb",  // assets 폴더 기준 경로
  scale: Vector3(0.2, 0.2, 0.2),
  position: Vector3(0.0, 0.0, 0.0),
  rotation: Vector4(1.0, 0.0, 0.0, 0.0),
);

무료 3D 모델 소스 추천

AR 앱 개발할 때 3D 모델을 어디서 구하냐고? 걱정 마, 좋은 무료 소스들이 있어!

🌐 무료 3D 모델 사이트들 Sketchfab (sketchfab.com): 수백만 개의 3D 모델. 많은 모델이 GLTF/GLB 형식으로 다운로드 가능. 무료 모델도 많아.

Google Poly (poly.pizza): Google이 운영하던 Poly가 종료된 후 커뮤니티가 이어받은 사이트. CC 라이선스 모델들이 많아.

Khronos glTF Sample Models: glTF 공식 샘플 모델들. 오리(Duck), 박스(Box), 헬멧 등 테스트용으로 딱이야.
GitHub: KhronosGroup/glTF-Sample-Models

Mixamo (mixamo.com): Adobe가 운영하는 캐릭터 + 애니메이션 사이트. 무료로 사용 가능.

ARNode의 Transform 이해하기

3D 공간에서 오브젝트의 위치, 크기, 회전을 제어하는 방법을 알아보자.

import 'package:vector_math/vector_math_64.dart';

ARNode myNode = ARNode(
  type: NodeType.webGLB,
  uri: "https://example.com/model.glb",
  
  // 위치: X(좌우), Y(상하), Z(앞뒤) - 단위: 미터
  position: Vector3(0.0, 0.0, 0.0),
  
  // 크기: 1.0이 원본 크기
  // 0.2면 원본의 20% 크기
  scale: Vector3(0.2, 0.2, 0.2),
  
  // 회전: Quaternion 형식 (x, y, z, w)
  // 기본값: Vector4(1.0, 0.0, 0.0, 0.0) = 회전 없음
  rotation: Vector4(1.0, 0.0, 0.0, 0.0),
  
  // 노드 이름 (나중에 식별할 때 사용)
  name: "myDuck",
  
  // 캔버스 크기 (일부 모델에 필요)
  canvasSize: 1000,
);
⚠️ Quaternion 회전 주의! rotation은 Quaternion(사원수) 형식이야. 일반적인 오일러 각도(degree)가 아니야! 예를 들어 Y축으로 90도 회전하려면 Vector4(0.0, 0.707, 0.0, 0.707)이야. Quaternion이 낯설다면 온라인 변환기를 활용해봐.

🗺️

평면 감지와 히트 테스트: AR의 핵심 메커니즘

AR 앱에서 "바닥에 오브젝트를 올려놓는" 기능이 어떻게 동작하는지 궁금하지 않아? 그 비밀이 바로 평면 감지(Plane Detection)와 히트 테스트(Hit Test)야!

평면 감지 설정

ARView를 생성할 때 어떤 종류의 평면을 감지할지 설정할 수 있어.

// PlaneDetectionConfig 옵션들
ARView(
  onARViewCreated: onARViewCreated,
  
  // 수평 평면만 감지 (바닥, 테이블)
  planeDetectionConfig: PlaneDetectionConfig.horizontal,
  
  // 수직 평면만 감지 (벽)
  // planeDetectionConfig: PlaneDetectionConfig.vertical,
  
  // 수평 + 수직 모두 감지
  // planeDetectionConfig: PlaneDetectionConfig.horizontalAndVertical,
  
  // 평면 감지 비활성화
  // planeDetectionConfig: PlaneDetectionConfig.none,
)

히트 테스트 결과 분석

사용자가 화면을 탭하면 히트 테스트가 실행돼. 이건 탭한 화면 좌표에서 현실 공간으로 광선(Ray)을 쏴서 무엇에 맞는지 확인하는 거야.

// 히트 테스트 결과 처리
void onPlaneOrPointTapped(List<ARHitTestResult> hitTestResults) {
  if (hitTestResults.isEmpty) return;
  
  // 히트 테스트 결과 타입별 처리
  for (var result in hitTestResults) {
    switch (result.type) {
      case ARHitTestResultType.plane:
        // 감지된 평면에 히트! 가장 신뢰도 높음
        print("평면 히트: ${result.worldTransform}");
        _placeObjectOnPlane(result);
        break;
        
      case ARHitTestResultType.featurePoint:
        // 특징점에 히트 (평면보다 덜 정확)
        print("특징점 히트");
        break;
        
      case ARHitTestResultType.estimatedHorizontalPlane:
        // 추정된 수평 평면 (아직 완전히 감지되지 않은 평면)
        print("추정 수평 평면 히트");
        break;
    }
  }
}

// 평면에 오브젝트 배치
Future<void> _placeObjectOnPlane(ARHitTestResult hitResult) async {
  // 히트 결과의 worldTransform을 앵커로 사용
  var anchor = ARPlaneAnchor(
    transformation: hitResult.worldTransform,
  );
  
  bool? anchorAdded = await arAnchorManager!.addAnchor(anchor);
  
  if (anchorAdded == true) {
    var node = ARNode(
      type: NodeType.webGLB,
      uri: "https://example.com/model.glb",
      scale: Vector3(0.15, 0.15, 0.15),
      position: Vector3(0.0, 0.0, 0.0),
      rotation: Vector4(1.0, 0.0, 0.0, 0.0),
    );
    
    await arObjectManager!.addNode(node, planeAnchor: anchor);
    anchors.add(anchor);
    nodes.add(node);
  }
}

평면 시각화 커스터마이징

감지된 평면을 시각적으로 표시할 때 기본 격자 패턴 대신 커스텀 텍스처를 사용할 수 있어.

// 커스텀 평면 텍스처 사용
arSessionManager!.onInitialize(
  showPlanes: true,
  // assets에 있는 이미지를 평면 텍스처로 사용
  customPlaneTexturePath: "assets/images/plane_texture.png",
  showFeaturePoints: false,
  showWorldOrigin: false,
  handleTaps: true,
);
💡 평면 감지 팁! ARCore/ARKit이 평면을 잘 감지하려면 몇 가지 조건이 필요해:
- 충분한 조명 (너무 어두우면 안 돼)
- 텍스처가 있는 표면 (완전히 흰 벽이나 유리는 어려워)
- 카메라를 천천히 움직이면서 스캔해야 해
- 처음 5~10초 정도 기다려야 평면이 감지돼

👆

AR 오브젝트 인터랙션: 드래그, 회전, 크기 조절

AR 앱에서 오브젝트를 그냥 배치만 하면 재미없잖아? 사용자가 오브젝트를 직접 만지고 움직일 수 있어야 진짜 AR 경험이지! ar_flutter_plugin은 드래그, 회전, 크기 조절 인터랙션을 지원해.

인터랙션 활성화

// 세션 초기화 시 인터랙션 활성화
arSessionManager!.onInitialize(
  showFeaturePoints: false,
  showPlanes: true,
  showWorldOrigin: false,
  handleTaps: true,      // 탭 처리
  handlePans: true,      // 드래그 처리
  handleRotation: true,  // 회전 처리
);

드래그(Pan) 이벤트 처리

// 드래그 이벤트 핸들러 등록
arObjectManager!.onPanStart = (String nodeName) {
  print("드래그 시작: $nodeName");
  setState(() {
    // UI 업데이트 (예: 선택된 오브젝트 하이라이트)
    selectedNodeName = nodeName;
  });
};

arObjectManager!.onPanChange = (String nodeName) {
  // 드래그 중 - 매 프레임 호출됨
  // 너무 많은 작업은 성능에 영향을 줄 수 있어
};

arObjectManager!.onPanEnd = (String nodeName, Matrix4 newTransformation) {
  print("드래그 종료: $nodeName");
  print("새로운 변환 행렬: $newTransformation");
  
  // 새 위치 저장
  setState(() {
    nodeTransformations[nodeName] = newTransformation;
    selectedNodeName = null;
  });
};

회전 이벤트 처리

// 회전 이벤트 핸들러
arObjectManager!.onRotationStart = (String nodeName) {
  print("회전 시작: $nodeName");
};

arObjectManager!.onRotationChange = (String nodeName) {
  // 회전 중
};

arObjectManager!.onRotationEnd = (String nodeName, Matrix4 newTransformation) {
  print("회전 종료: $nodeName");
  // 새 회전값 저장
};

노드 탭 이벤트

// 노드 탭 이벤트
arObjectManager!.onNodeTap = (List<String> tappedNodes) {
  if (tappedNodes.isEmpty) return;
  
  String tappedNodeName = tappedNodes.first;
  print("탭된 노드: $tappedNodeName");
  
  // 탭된 노드 찾기
  ARNode? tappedNode = nodes.firstWhere(
    (node) => node.name == tappedNodeName,
    orElse: () => null,
  );
  
  if (tappedNode != null) {
    // 탭된 노드 제거
    arObjectManager!.removeNode(tappedNode);
    nodes.remove(tappedNode);
    
    // 또는 다른 처리 (색상 변경, 정보 표시 등)
    showNodeInfo(tappedNodeName);
  }
};

프로그래밍 방식으로 노드 변환하기

사용자 인터랙션 외에도 코드로 직접 노드의 위치, 크기, 회전을 변경할 수 있어.

// 노드 변환 업데이트
Future<void> updateNodeTransform(ARNode node) async {
  // 새 위치로 이동
  node.position = Vector3(0.5, 0.0, 0.0);  // X축으로 0.5m 이동
  
  // 크기 변경
  node.scale = Vector3(0.3, 0.3, 0.3);
  
  // 회전 변경 (Y축 45도 회전 Quaternion)
  node.rotation = Vector4(0.0, 0.383, 0.0, 0.924);
  
  // 변환 적용
  await arObjectManager!.transformationChanged(node);
}

// 애니메이션 효과로 크기 변경
Future<void> animateNodeScale(ARNode node) async {
  for (double scale = 0.1; scale <= 0.5; scale += 0.05) {
    node.scale = Vector3(scale, scale, scale);
    await arObjectManager!.transformationChanged(node);
    await Future.delayed(const Duration(milliseconds: 50));
  }
}

🛋️

실전 프로젝트: 가구 AR 배치 앱 만들기

이론은 충분히 배웠으니 이제 실전이야! 이케아 앱처럼 가구를 AR로 배치해볼 수 있는 미니 앱을 만들어보자. 이 프로젝트를 통해 지금까지 배운 내용을 종합적으로 활용할 수 있어. 🛋️

참고로, 이런 AR 앱 개발 프로젝트를 진행할 때 재능넷같은 플랫폼에서 Flutter 전문가를 찾아 협업하는 것도 좋은 방법이야. 복잡한 3D 모델링이나 UI/UX 디자인 부분은 전문가의 도움을 받으면 훨씬 퀄리티가 올라가거든!

앱 구조 설계

📋 가구 AR 배치 앱 기능 목록
  • ✅ 카메라 뷰에서 바닥 평면 감지
  • ✅ 하단 가구 선택 패널 (소파, 의자, 테이블 등)
  • ✅ 탭으로 가구 배치
  • ✅ 드래그로 가구 위치 이동
  • ✅ 핀치 제스처로 크기 조절
  • ✅ 회전 제스처로 방향 변경
  • ✅ 배치된 가구 목록 표시
  • ✅ 스크린샷 저장 기능
// furniture_ar_app.dart - 가구 AR 배치 앱 전체 코드

import 'package:flutter/material.dart';
import 'package:ar_flutter_plugin/ar_flutter_plugin.dart';
import 'package:ar_flutter_plugin/datatypes/config_planedetection.dart';
import 'package:ar_flutter_plugin/datatypes/node_types.dart';
import 'package:ar_flutter_plugin/datatypes/hittest_result_types.dart';
import 'package:ar_flutter_plugin/managers/ar_anchor_manager.dart';
import 'package:ar_flutter_plugin/managers/ar_location_manager.dart';
import 'package:ar_flutter_plugin/managers/ar_object_manager.dart';
import 'package:ar_flutter_plugin/managers/ar_session_manager.dart';
import 'package:ar_flutter_plugin/models/ar_anchor.dart';
import 'package:ar_flutter_plugin/models/ar_node.dart';
import 'package:ar_flutter_plugin/models/ar_hittest_result.dart';
import 'package:vector_math/vector_math_64.dart';

// 가구 데이터 모델
class FurnitureItem {
  final String name;
  final String modelUrl;
  final String emoji;
  final double defaultScale;
  
  const FurnitureItem({
    required this.name,
    required this.modelUrl,
    required this.emoji,
    required this.defaultScale,
  });
}

// 가구 목록 (실제 앱에서는 GLB 파일 URL 사용)
const List<FurnitureItem> furnitureItems = [
  FurnitureItem(
    name: "오리",
    modelUrl: "https://github.com/KhronosGroup/glTF-Sample-Models/raw/master/2.0/Duck/glTF-Binary/Duck.glb",
    emoji: "🦆",
    defaultScale: 0.15,
  ),
  FurnitureItem(
    name: "헬멧",
    modelUrl: "https://github.com/KhronosGroup/glTF-Sample-Models/raw/master/2.0/DamagedHelmet/glTF-Binary/DamagedHelmet.glb",
    emoji: "⛑️",
    defaultScale: 0.3,
  ),
  FurnitureItem(
    name: "박스",
    modelUrl: "https://github.com/KhronosGroup/glTF-Sample-Models/raw/master/2.0/Box/glTF-Binary/Box.glb",
    emoji: "📦",
    defaultScale: 0.2,
  ),
];

class FurnitureARApp extends StatefulWidget {
  const FurnitureARApp({Key? key}) : super(key: key);

  @override
  State<FurnitureARApp> createState() => _FurnitureARAppState();
}

class _FurnitureARAppState extends State<FurnitureARApp> {
  ARSessionManager? arSessionManager;
  ARObjectManager? arObjectManager;
  ARAnchorManager? arAnchorManager;
  
  List<ARNode> nodes = [];
  List<ARAnchor> anchors = [];
  
  FurnitureItem? selectedFurniture;
  bool isPlaneDetected = false;
  String statusMessage = "카메라를 바닥을 향해 천천히 움직여주세요";

  @override
  void dispose() {
    arSessionManager?.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Stack(
        children: [
          // AR 뷰
          ARView(
            onARViewCreated: onARViewCreated,
            planeDetectionConfig: PlaneDetectionConfig.horizontal,
          ),
          
          // 상단 상태 메시지
          Positioned(
            top: MediaQuery.of(context).padding.top + 10,
            left: 16,
            right: 16,
            child: Container(
              padding: const EdgeInsets.symmetric(
                horizontal: 16, vertical: 10,
              ),
              decoration: BoxDecoration(
                color: Colors.black.withOpacity(0.6),
                borderRadius: BorderRadius.circular(20),
              ),
              child: Text(
                statusMessage,
                style: const TextStyle(color: Colors.white, fontSize: 14),
                textAlign: TextAlign.center,
              ),
            ),
          ),
          
          // 하단 가구 선택 패널
          Positioned(
            bottom: 0,
            left: 0,
            right: 0,
            child: _buildFurniturePanel(),
          ),
          
          // 우측 액션 버튼들
          Positioned(
            right: 16,
            top: MediaQuery.of(context).padding.top + 60,
            child: Column(
              children: [
                _buildActionButton(
                  icon: Icons.camera_alt,
                  onPressed: _takeScreenshot,
                  tooltip: "스크린샷",
                ),
                const SizedBox(height: 8),
                _buildActionButton(
                  icon: Icons.delete_sweep,
                  onPressed: _removeAllObjects,
                  tooltip: "모두 지우기",
                  color: Colors.red.withOpacity(0.8),
                ),
              ],
            ),
          ),
        ],
      ),
    );
  }
  
  // 가구 선택 패널 위젯
  Widget _buildFurniturePanel() {
    return Container(
      height: 130,
      decoration: BoxDecoration(
        color: Colors.white.withOpacity(0.92),
        borderRadius: const BorderRadius.vertical(top: Radius.circular(20)),
        boxShadow: [
          BoxShadow(
            color: Colors.black.withOpacity(0.1),
            blurRadius: 10,
            offset: const Offset(0, -2),
          ),
        ],
      ),
      child: Column(
        children: [
          const Padding(
            padding: EdgeInsets.only(top: 12, bottom: 6),
            child: Text(
              "배치할 오브젝트 선택",
              style: TextStyle(
                fontSize: 13,
                color: Colors.grey,
                fontWeight: FontWeight.w600,
              ),
            ),
          ),
          Expanded(
            child: ListView.builder(
              scrollDirection: Axis.horizontal,
              padding: const EdgeInsets.symmetric(horizontal: 16),
              itemCount: furnitureItems.length,
              itemBuilder: (context, index) {
                final item = furnitureItems[index];
                final isSelected = selectedFurniture?.name == item.name;
                
                return GestureDetector(
                  onTap: () {
                    setState(() {
                      selectedFurniture = item;
                      statusMessage = "${item.name}을(를) 선택했어요. 바닥을 탭해서 배치하세요!";
                    });
                  },
                  child: Container(
                    width: 80,
                    margin: const EdgeInsets.only(right: 12),
                    decoration: BoxDecoration(
                      color: isSelected 
                        ? const Color(0xFF5b9ec9).withOpacity(0.15)
                        : Colors.grey.withOpacity(0.08),
                      borderRadius: BorderRadius.circular(12),
                      border: Border.all(
                        color: isSelected 
                          ? const Color(0xFF5b9ec9)
                          : Colors.transparent,
                        width: 2,
                      ),
                    ),
                    child: Column(
                      mainAxisAlignment: MainAxisAlignment.center,
                      children: [
                        Text(item.emoji, style: const TextStyle(fontSize: 28)),
                        const SizedBox(height: 4),
                        Text(
                          item.name,
                          style: TextStyle(
                            fontSize: 11,
                            color: isSelected 
                              ? const Color(0xFF3a7aa8)
                              : Colors.grey[600],
                            fontWeight: isSelected 
                              ? FontWeight.bold 
                              : FontWeight.normal,
                          ),
                        ),
                      ],
                    ),
                  ),
                );
              },
            ),
          ),
        ],
      ),
    );
  }
  
  // 액션 버튼 위젯
  Widget _buildActionButton({
    required IconData icon,
    required VoidCallback onPressed,
    required String tooltip,
    Color? color,
  }) {
    return Tooltip(
      message: tooltip,
      child: GestureDetector(
        onTap: onPressed,
        child: Container(
          width: 44,
          height: 44,
          decoration: BoxDecoration(
            color: color ?? Colors.white.withOpacity(0.9),
            borderRadius: BorderRadius.circular(22),
            boxShadow: [
              BoxShadow(
                color: Colors.black.withOpacity(0.15),
                blurRadius: 6,
                offset: const Offset(0, 2),
              ),
            ],
          ),
          child: Icon(
            icon,
            size: 22,
            color: color != null ? Colors.white : Colors.grey[700],
          ),
        ),
      ),
    );
  }
  
  // AR 뷰 생성 콜백
  void onARViewCreated(
    ARSessionManager sessionManager,
    ARObjectManager objectManager,
    ARAnchorManager anchorManager,
    ARLocationManager locationManager,
  ) {
    arSessionManager = sessionManager;
    arObjectManager = objectManager;
    arAnchorManager = anchorManager;

    arSessionManager!.onInitialize(
      showFeaturePoints: false,
      showPlanes: true,
      showWorldOrigin: false,
      handleTaps: true,
      handlePans: true,
      handleRotation: true,
    );
    
    arObjectManager!.onInitialize();
    
    // 이벤트 핸들러 등록
    arSessionManager!.onPlaneOrPointTap = _onPlaneOrPointTapped;
    arObjectManager!.onNodeTap = _onNodeTapped;
    arObjectManager!.onPanEnd = _onPanEnd;
    arObjectManager!.onRotationEnd = _onRotationEnd;
    
    // 평면 감지 상태 업데이트 (실제로는 ARCore 콜백 활용)
    Future.delayed(const Duration(seconds: 3), () {
      if (mounted) {
        setState(() {
          isPlaneDetected = true;
          statusMessage = "바닥이 감지됐어요! 오브젝트를 선택하고 탭해서 배치하세요";
        });
      }
    });
  }
  
  // 평면 탭 처리
  Future<void> _onPlaneOrPointTapped(
    List<ARHitTestResult> hitTestResults,
  ) async {
    if (selectedFurniture == null) {
      setState(() {
        statusMessage = "먼저 하단에서 배치할 오브젝트를 선택해주세요!";
      });
      return;
    }
    
    // 평면 히트 결과 찾기
    ARHitTestResult? planeHit;
    try {
      planeHit = hitTestResults.firstWhere(
        (r) => r.type == ARHitTestResultType.plane,
      );
    } catch (e) {
      planeHit = hitTestResults.isNotEmpty ? hitTestResults.first : null;
    }
    
    if (planeHit == null) return;
    
    // 앵커 생성
    var anchor = ARPlaneAnchor(
      transformation: planeHit.worldTransform,
    );
    
    bool? anchorAdded = await arAnchorManager!.addAnchor(anchor);
    
    if (anchorAdded == true) {
      anchors.add(anchor);
      
      // 선택된 가구 노드 생성
      double s = selectedFurniture!.defaultScale;
      var node = ARNode(
        type: NodeType.webGLB,
        uri: selectedFurniture!.modelUrl,
        scale: Vector3(s, s, s),
        position: Vector3(0.0, 0.0, 0.0),
        rotation: Vector4(1.0, 0.0, 0.0, 0.0),
        name: "${selectedFurniture!.name}_${DateTime.now().millisecondsSinceEpoch}",
      );
      
      bool? nodeAdded = await arObjectManager!.addNode(
        node,
        planeAnchor: anchor,
      );
      
      if (nodeAdded == true) {
        nodes.add(node);
        setState(() {
          statusMessage = "${selectedFurniture!.name} 배치 완료! 드래그해서 이동하거나 회전할 수 있어요";
        });
      }
    }
  }
  
  // 노드 탭 처리 (탭하면 제거)
  void _onNodeTapped(List<String> tappedNodes) {
    if (tappedNodes.isEmpty) return;
    
    // 탭된 노드 찾아서 제거
    String tappedName = tappedNodes.first;
    ARNode? nodeToRemove;
    
    try {
      nodeToRemove = nodes.firstWhere((n) => n.name == tappedName);
    } catch (e) {
      return;
    }
    
    // 확인 다이얼로그
    showDialog(
      context: context,
      builder: (ctx) => AlertDialog(
        title: const Text("오브젝트 제거"),
        content: Text("$tappedName을(를) 제거할까요?"),
        actions: [
          TextButton(
            onPressed: () => Navigator.pop(ctx),
            child: const Text("취소"),
          ),
          TextButton(
            onPressed: () async {
              Navigator.pop(ctx);
              await arObjectManager!.removeNode(nodeToRemove!);
              setState(() {
                nodes.remove(nodeToRemove);
              });
            },
            child: const Text("제거", style: TextStyle(color: Colors.red)),
          ),
        ],
      ),
    );
  }
  
  void _onPanEnd(String nodeName, Matrix4 newTransformation) {
    setState(() {
      statusMessage = "위치 이동 완료!";
    });
  }
  
  void _onRotationEnd(String nodeName, Matrix4 newTransformation) {
    setState(() {
      statusMessage = "회전 완료!";
    });
  }
  
  // 스크린샷
  Future<void> _takeScreenshot() async {
    var screenshot = await arSessionManager!.snapshot();
    if (screenshot != null) {
      // 갤러리에 저장하거나 공유하는 로직 추가
      ScaffoldMessenger.of(context).showSnackBar(
        const SnackBar(content: Text("스크린샷이 저장됐어요! 📸")),
      );
    }
  }
  
  // 모든 오브젝트 제거
  Future<void> _removeAllObjects() async {
    for (var node in List.from(nodes)) {
      await arObjectManager!.removeNode(node);
    }
    for (var anchor in List.from(anchors)) {
      await arAnchorManager!.removeAnchor(anchor);
    }
    setState(() {
      nodes.clear();
      anchors.clear();
      statusMessage = "모두 지웠어요! 다시 배치해보세요";
    });
  }
}
💡 실전 팁! 위 코드는 완전히 동작하는 가구 AR 배치 앱의 기본 구조야. 실제 서비스 앱을 만들 때는 여기에 더해서:
- 실제 가구 3D 모델 GLB 파일 준비
- 가구 정보(가격, 사이즈) 표시 UI
- 장바구니 연동
- 소셜 공유 기능
등을 추가하면 완성도 높은 앱이 돼!

☁️

Cloud Anchors: 여러 기기에서 AR 공유하기

AR의 진짜 매력 중 하나는 멀티플레이어 AR이야. 내가 배치한 AR 오브젝트를 친구 폰에서도 같은 위치에서 볼 수 있다면 얼마나 신기하겠어? 이걸 가능하게 하는 게 바로 Cloud Anchors야!

Cloud Anchors란?

Cloud Anchors는 ARCore의 기능으로, 앵커 정보를 Google 서버에 업로드해서 다른 기기에서도 같은 앵커를 사용할 수 있게 해줘. 이를 통해 여러 사람이 같은 AR 경험을 공유할 수 있어.

☁️ Cloud Anchors 동작 원리 1. 호스트 기기: 앵커를 생성하고 Google ARCore Cloud Anchors API에 업로드. 고유한 Cloud Anchor ID를 받아.

2. Cloud Anchor ID 공유: 이 ID를 다른 기기에 전달 (QR코드, 딥링크, 서버 등을 통해).

3. 게스트 기기: Cloud Anchor ID로 앵커를 다운로드. 같은 물리적 공간에서 동일한 위치에 앵커가 생성돼.

4. 공유 AR 경험: 두 기기 모두 같은 위치에 AR 오브젝트를 볼 수 있어!

Cloud Anchors 구현

Cloud Anchors를 사용하려면 먼저 Google Cloud Console에서 ARCore API를 활성화하고 API 키를 발급받아야 해.

// Cloud Anchor 업로드 (호스트)
Future<void> uploadCloudAnchor(ARPlaneAnchor localAnchor) async {
  // 로컬 앵커를 클라우드에 업로드
  arAnchorManager!.onAnchorUploaded = (ARPlaneAnchor uploadedAnchor) {
    String? cloudAnchorId = uploadedAnchor.cloudanchorid;
    
    if (cloudAnchorId != null) {
      print("Cloud Anchor ID: $cloudAnchorId");
      
      // 이 ID를 다른 사용자에게 공유
      // 예: 서버에 저장, QR코드 생성, 클립보드 복사 등
      _shareCloudAnchorId(cloudAnchorId);
    }
  };
  
  // 앵커 업로드 시작
  await arAnchorManager!.uploadAnchor(localAnchor);
}

// Cloud Anchor 다운로드 (게스트)
Future<void> downloadCloudAnchor(String cloudAnchorId) async {
  arAnchorManager!.onAnchorDownloaded = (ARPlaneAnchor downloadedAnchor) {
    // 다운로드된 앵커에 노드 추가
    _addNodeToAnchor(downloadedAnchor);
  };
  
  // 앵커 다운로드
  await arAnchorManager!.downloadAnchor(cloudAnchorId);
}

// 공유 AR 경험 구현 예시
class SharedARExperience extends StatefulWidget {
  final bool isHost;
  final String? cloudAnchorId;  // 게스트용
  
  const SharedARExperience({
    Key? key,
    required this.isHost,
    this.cloudAnchorId,
  }) : super(key: key);
  
  @override
  State<SharedARExperience> createState() => _SharedARExperienceState();
}
⚠️ Cloud Anchors 제한사항 - 두 기기가 같은 물리적 공간에 있어야 해 (또는 충분히 비슷한 환경)
- ARCore Cloud Anchors API 사용량 제한이 있어 (무료 티어: 하루 1000회)
- 앵커 유효 기간: 기본 24시간 (최대 365일까지 연장 가능)
- iOS에서는 ARKit을 사용하므로 Cloud Anchors가 제한적으로 지원돼

⚡

AR 앱 성능 최적화 전략

AR 앱은 카메라 처리, 3D 렌더링, 모션 트래킹을 동시에 하기 때문에 배터리와 CPU를 많이 써. 성능 최적화는 AR 앱 개발에서 정말 중요한 부분이야!

3D 모델 최적화

🎨 3D 모델 최적화 체크리스트 폴리곤 수 줄이기: 모바일 AR에서는 모델당 폴리곤 수를 10,000개 이하로 유지하는 게 좋아. Blender나 Maya에서 LOD(Level of Detail)를 적용해봐.

텍스처 크기 최적화: 텍스처는 최대 1024x1024px 또는 2048x2048px로 제한해. 4K 텍스처는 모바일에서 너무 무거워.

텍스처 압축: KTX2 형식의 압축 텍스처를 사용하면 메모리를 크게 줄일 수 있어.

GLB 파일 크기: 모델 파일은 가능하면 5MB 이하로 유지해. 큰 파일은 로딩 시간이 길어져.

불필요한 메시 제거: 보이지 않는 내부 면이나 중복 버텍스를 제거해.

코드 레벨 최적화

// 1. 노드 재사용 - 같은 모델을 여러 번 배치할 때
// 나쁜 예: 매번 새 노드 생성
Future<void> badPlaceObject(ARHitTestResult hit) async {
  var node = ARNode(
    type: NodeType.webGLB,
    uri: "https://example.com/heavy_model.glb",  // 매번 다운로드!
    ...
  );
}

// 좋은 예: 모델 URI를 캐시하고 재사용
final String _modelUri = "https://example.com/model.glb";

Future<void> goodPlaceObject(ARHitTestResult hit) async {
  var node = ARNode(
    type: NodeType.webGLB,
    uri: _modelUri,  // 같은 URI는 캐시됨
    ...
  );
}

// 2. 불필요한 setState 줄이기
// 나쁜 예: 드래그 중 매 프레임 setState
arObjectManager!.onPanChange = (nodeName) {
  setState(() { /* 불필요한 리빌드 */ });
};

// 좋은 예: 드래그 종료 시에만 setState
arObjectManager!.onPanEnd = (nodeName, transform) {
  setState(() {
    // 필요한 상태만 업데이트
    lastTransform = transform;
  });
};

// 3. 오브젝트 수 제한
const int maxObjects = 10;  // 동시에 최대 10개만 배치

Future<void> placeObjectWithLimit(ARHitTestResult hit) async {
  if (nodes.length >= maxObjects) {
    ScaffoldMessenger.of(context).showSnackBar(
      const SnackBar(content: Text("최대 10개까지만 배치할 수 있어요")),
    );
    return;
  }
  // 오브젝트 배치 로직...
}

// 4. 평면 감지 최적화
// 오브젝트 배치 후 평면 감지 비활성화 (배터리 절약)
Future<void> disablePlaneDetectionAfterPlacement() async {
  // ARCore/ARKit 세션 설정 업데이트
  // (ar_flutter_plugin에서 직접 지원하지 않을 수 있음)
}

메모리 관리

// 올바른 리소스 해제
@override
void dispose() {
  // AR 세션 반드시 종료!
  arSessionManager?.dispose();
  
  // 노드와 앵커 리스트 초기화
  nodes.clear();
  anchors.clear();
  
  super.dispose();
}

// 앱이 백그라운드로 갈 때 AR 세션 일시정지
@override
void didChangeAppLifecycleState(AppLifecycleState state) {
  if (state == AppLifecycleState.paused) {
    // AR 세션 일시정지 (배터리 절약)
    arSessionManager?.dispose();
  } else if (state == AppLifecycleState.resumed) {
    // AR 세션 재시작
    // (페이지 재빌드 필요)
  }
}

성능 모니터링

📊 AR 앱 성능 목표치 프레임 레이트: 최소 30fps, 이상적으로 60fps 유지
메모리 사용량: 앱 전체 200MB 이하 권장
배터리 소모: 1시간 사용 시 30% 이하 소모 목표
모델 로딩 시간: 3초 이내 (로딩 인디케이터 필수)
히트 테스트 응답: 탭 후 0.5초 이내 오브젝트 배치

🐛

AR 개발 디버깅과 자주 만나는 문제들

AR 개발하다 보면 진짜 별의별 문제를 다 만나게 돼. 에뮬레이터에서는 안 되고, 실기기에서만 테스트해야 하고... 자주 만나는 문제들과 해결책을 정리해줄게!

자주 만나는 에러들

에러/문제 원인 해결책
ARCore not supported 기기가 ARCore 미지원 ARCore 지원 기기 목록 확인, 에뮬레이터 대신 실기기 사용
Camera permission denied 카메라 권한 없음 AndroidManifest.xml에 권한 추가, 런타임 권한 요청
Model not loading URL 오류 또는 네트워크 문제 URL 확인, 인터넷 권한 추가, 로컬 파일 사용 고려
Plane not detected 조명 부족 또는 텍스처 없는 표면 밝은 환경에서 테스트, 카메라 천천히 이동
iOS Pod install 실패 CocoaPods 버전 문제 pod repo update 후 재시도, Podfile platform 버전 확인
minSdkVersion 오류 Android minSdk가 24 미만 build.gradle에서 minSdkVersion 24로 변경

AR 에뮬레이터 설정

실기기 없이 개발할 때는 Android 에뮬레이터에서 ARCore를 시뮬레이션할 수 있어.

// Android 에뮬레이터에서 ARCore 사용하기
// 1. Android Studio에서 AVD Manager 열기
// 2. API 24+ 이미지 선택 (x86_64 권장)
// 3. 에뮬레이터 실행 후 ARCore 설치:
//    adb install -r arcore-preview.apk
// 4. 에뮬레이터에서 AR 씬 시뮬레이션:
//    - Extended Controls > Camera > Virtual Scene 사용
//    - 가상 환경에서 카메라 이동 가능

디버깅 팁

// AR 세션 에러 핸들링
arSessionManager!.onError = (String errorMessage) {
  print("🚨 AR 에러: $errorMessage");
  
  // 사용자에게 에러 표시
  if (mounted) {
    ScaffoldMessenger.of(context).showSnackBar(
      SnackBar(
        content: Text("AR 오류: $errorMessage"),
        backgroundColor: Colors.red,
      ),
    );
  }
};

// 디버그 모드에서 추가 정보 표시
arSessionManager!.onInitialize(
  showFeaturePoints: true,   // 특징점 표시 (디버그용)
  showPlanes: true,          // 평면 표시
  showWorldOrigin: true,     // 좌표축 표시 (디버그용)
  handleTaps: true,
);

// 히트 테스트 결과 디버깅
void debugHitTestResults(List<ARHitTestResult> results) {
  print("히트 테스트 결과 수: ${results.length}");
  for (var result in results) {
    print("타입: ${result.type}");
    print("변환 행렬: ${result.worldTransform}");
  }
}
💡 AR 개발의 황금 법칙 AR 앱은 반드시 실기기에서 테스트해야 해! 에뮬레이터는 기본적인 동작 확인용이고, 실제 AR 경험은 실기기에서만 제대로 확인할 수 있어. 특히 평면 감지, 조명 추정, 모션 트래킹은 실기기 테스트가 필수야.

🚀

고급 기능: 이미지 트래킹과 Face AR

기본 평면 감지 AR을 넘어서 더 고급 기능들도 있어. 이미지를 인식해서 AR을 띄우거나, 얼굴을 추적하는 기능들이야. 이런 기능들은 마케팅, 교육, 엔터테인먼트 분야에서 정말 많이 쓰여!

이미지 트래킹 (Image Tracking)

특정 이미지(마커)를 카메라로 인식하면 그 위에 AR 콘텐츠를 표시하는 기능이야. 명함, 포스터, 책 표지 등에 활용할 수 있어.

// 이미지 트래킹 설정 (ARCore Image Tracking)
// ar_flutter_plugin에서는 네이티브 플러그인 채널을 통해 구현 가능

// 참조 이미지 데이터베이스 설정 (Android ARCore)
// android/app/src/main/assets/ar_images/ 폴더에 이미지 추가

// 이미지 트래킹 활성화
arSessionManager!.onInitialize(
  // 이미지 트래킹은 별도 설정 필요
  showFeaturePoints: false,
  showPlanes: false,  // 이미지 트래킹 시 평면 감지 비활성화
  handleTaps: false,
);

// 이미지 감지 이벤트 처리
// (ar_flutter_plugin의 확장 기능 또는 네이티브 채널 활용)
arSessionManager!.onImageDetected = (String imageName, Matrix4 transform) {
  print("이미지 감지: $imageName");
  
  // 감지된 이미지 위에 AR 콘텐츠 배치
  _placeARContentOnImage(imageName, transform);
};

AR 씬에 텍스트 표시하기

3D 오브젝트 외에도 텍스트를 AR 공간에 표시할 수 있어. 제품 정보, 가격표, 설명 등을 AR로 표시하는 데 유용해.

// AR 텍스트 노드 생성
// ar_flutter_plugin에서는 직접적인 텍스트 노드를 지원하지 않아
// 대신 텍스트가 포함된 GLB 모델을 사용하거나
// Flutter 위젯을 AR 뷰 위에 오버레이하는 방식을 사용해

// 방법 1: Flutter 위젯 오버레이
Stack(
  children: [
    ARView(onARViewCreated: onARViewCreated, ...),
    
    // AR 오브젝트 위치에 Flutter 위젯 오버레이
    // (3D 좌표를 2D 화면 좌표로 변환 필요)
    Positioned(
      left: screenX,
      top: screenY,
      child: Container(
        padding: const EdgeInsets.all(8),
        decoration: BoxDecoration(
          color: Colors.black.withOpacity(0.7),
          borderRadius: BorderRadius.circular(8),
        ),
        child: const Text(
          "소파 - 299,000원",
          style: TextStyle(color: Colors.white, fontSize: 14),
        ),
      ),
    ),
  ],
)

AR 애니메이션

GLB 파일에 포함된 애니메이션을 재생하는 것도 가능해. 걷는 캐릭터, 회전하는 제품 등을 표현할 수 있어.

// 애니메이션이 포함된 GLB 모델 사용
// Mixamo에서 다운로드한 캐릭터 + 애니메이션 GLB 파일

ARNode animatedNode = ARNode(
  type: NodeType.webGLB,
  // 애니메이션이 포함된 GLB 파일
  uri: "https://example.com/walking_character.glb",
  scale: Vector3(0.5, 0.5, 0.5),
  position: Vector3(0.0, 0.0, 0.0),
  rotation: Vector4(1.0, 0.0, 0.0, 0.0),
);

// GLB 파일 내 애니메이션은 자동으로 재생돼
// 특정 애니메이션 클립 제어는 네이티브 채널을 통해 구현 가능

💼

Flutter AR 앱의 실제 활용 사례들

이론과 코드를 충분히 봤으니 이제 실제로 어떤 앱들이 이런 기술을 쓰는지 살펴보자. 아이디어를 얻는 데도 도움이 될 거야!

🛋️ 인테리어/가구 분야 이케아 플레이스(IKEA Place), 웨이페어(Wayfair) 같은 앱들이 AR로 가구를 방에 배치해볼 수 있게 해줘. 구매 전 실제 크기와 색상을 확인할 수 있어서 반품률이 크게 줄었대. Flutter로 이런 앱을 만들 때 ar_flutter_plugin이 딱이야!
🎓 교육 분야 3D 인체 모델을 AR로 보여주는 의학 교육 앱, 역사적 건물을 AR로 복원하는 역사 교육 앱, 분자 구조를 3D로 보여주는 화학 교육 앱 등. 교육 분야에서 AR은 정말 강력한 도구야. 추상적인 개념을 시각화할 수 있거든.
🛒 이커머스/리테일 안경을 가상으로 써보는 앱, 화장품 색상을 얼굴에 테스트하는 앱, 신발을 발에 신어보는 앱 등. 온라인 쇼핑의 가장 큰 단점인 "직접 입어볼 수 없다"는 문제를 AR이 해결해줘.
🏗️ 건축/부동산 건물이 완공되기 전에 AR로 미리 보여주는 앱, 인테리어 리모델링 전후를 AR로 시뮬레이션하는 앱. 건설사나 부동산 회사들이 많이 활용하고 있어.
🎮 게임/엔터테인먼트 포켓몬 GO처럼 현실 공간에서 게임을 즐기는 앱, AR 보드게임, AR 탈출 게임 등. 게임 분야에서 AR은 완전히 새로운 경험을 만들어내.
🔧 산업/유지보수 기계 수리 시 AR로 단계별 가이드를 보여주는 앱, 건물 내 배관/전기 위치를 AR로 표시하는 앱. B2B 분야에서도 AR 활용이 빠르게 늘고 있어.

이런 다양한 분야에서 AR 앱 개발 수요가 늘어나면서, Flutter AR 개발 능력은 정말 가치 있는 스킬이 됐어. 재능넷에서도 Flutter AR 개발 관련 프리랜서 의뢰가 꾸준히 올라오고 있을 정도니까!

Flutter AR 앱 활용 분야 AR 🛋️ 인테리어 가구 배치 🎓 교육 3D 학습 🛒 이커머스 가상 착용 🎮 게임 AR 게임 🏗️ 건축 시뮬레이션 🔧 산업 유지보수

⚖️

ar_flutter_plugin의 한계와 대안 솔루션

ar_flutter_plugin이 정말 유용한 도구이긴 하지만, 솔직히 말해서 한계도 있어. 이걸 알아야 프로젝트에 맞는 도구를 선택할 수 있거든. 장단점을 냉정하게 살펴보자!

ar_flutter_plugin의 한계

⚠️ 알아두어야 할 한계점들 1. 유지보수 상태: 2024년 기준으로 ar_flutter_plugin의 업데이트 빈도가 줄어들었어. 최신 ARCore/ARKit 기능들이 즉시 반영되지 않을 수 있어.

2. 고급 기능 제한: 이미지 트래킹, 얼굴 트래킹, 물체 감지 등 고급 AR 기능은 직접 지원하지 않아. 네이티브 채널을 통해 구현해야 해.

3. 렌더링 품질: 네이티브 AR 앱에 비해 렌더링 품질이 다소 낮을 수 있어. 특히 복잡한 조명 효과나 그림자 처리에서 차이가 나.

4. 디버깅 어려움: Flutter와 네이티브 레이어 사이의 문제를 디버깅하기가 까다로울 수 있어.

5. 플랫폼 차이: iOS와 Android에서 동작이 완전히 동일하지 않을 수 있어. 플랫폼별 테스트가 필수야.

대안 솔루션들

솔루션 특징 적합한 경우
Unity + AR Foundation 강력한 3D 엔진, 풍부한 AR 기능 게임, 복잡한 3D 인터랙션
React Native + ViroReact JS 기반, 크로스 플랫폼 웹 개발자 팀
네이티브 ARCore/ARKit 최고 성능, 최신 기능 플랫폼별 최적화 필요 시
WebAR (8th Wall, Zappar) 앱 설치 불필요, 브라우저에서 동작 마케팅 캠페인, 빠른 배포
ar_flutter_plugin Flutter 통합, 크로스 플랫폼 Flutter 앱에 AR 기능 추가

언제 ar_flutter_plugin을 쓰면 좋을까?

✅ ar_flutter_plugin이 최적인 경우 - 이미 Flutter로 개발 중인 앱에 AR 기능을 추가할 때
- 기본적인 평면 감지 + 3D 오브젝트 배치가 주요 기능일 때
- 크로스 플랫폼(iOS + Android) 동시 지원이 필요할 때
- Flutter 팀이 네이티브 개발 경험이 없을 때
- 빠른 프로토타이핑이 필요할 때
❌ 다른 솔루션을 고려해야 할 경우 - 이미지 트래킹, 얼굴 트래킹 등 고급 AR 기능이 핵심일 때
- 최고 수준의 렌더링 품질이 필요할 때
- 복잡한 물리 시뮬레이션이 필요한 게임 개발 시
- 앱 설치 없이 AR을 제공해야 할 때 (WebAR 고려)

🎯

Flutter AR 개발 로드맵과 다음 단계

자, 이제 ar_flutter_plugin에 대해 꽤 많이 알게 됐지? 마지막으로 앞으로 어떻게 공부하고 발전시켜 나갈지 로드맵을 그려볼게!

단계별 학습 로드맵

1
기초 다지기 (1~2주)
Flutter 기본기 확인, Dart 언어 숙달, 3D 좌표계 이해 (X, Y, Z축), Quaternion 기초 이해
2
ar_flutter_plugin 기본 (2~3주)
플러그인 설치 및 설정, 기본 AR 뷰어 구현, 평면 감지 및 오브젝트 배치, 기본 인터랙션 구현
3
3D 모델 작업 (2~3주)
Blender 기초 학습, GLB/GLTF 형식 이해, 모델 최적화 기법, 텍스처 작업 기초
4
실전 프로젝트 (3~4주)
가구 배치 앱, 제품 뷰어 앱, 교육용 AR 앱 중 하나 선택해서 완성도 있게 구현
5
고급 기능 탐구 (지속적으로)
Cloud Anchors, 이미지 트래킹, 네이티브 채널 활용, 성능 최적화, 앱 스토어 배포

추천 학습 자료

📚 공식 문서 및 자료 ar_flutter_plugin GitHub: 공식 예제 코드와 README가 가장 정확한 자료야
URL: github.com/CariusLars/ar_flutter_plugin

Google ARCore 공식 문서: ARCore의 동작 원리를 깊이 이해하고 싶다면
URL: developers.google.com/ar

Apple ARKit 공식 문서: iOS AR 개발의 기초
URL: developer.apple.com/augmented-reality

Khronos glTF 스펙: 3D 모델 형식 이해
URL: www.khronos.org/gltf

커뮤니티와 협업

AR 개발은 혼자 하기엔 범위가 넓어. 3D 모델링, UI/UX 디자인, 백엔드 연동 등 다양한 전문성이 필요하거든. Flutter AR 개발 커뮤니티에 참여하거나, 필요한 부분은 전문가와 협업하는 것도 좋은 방법이야.

🌟 마지막 한마디 AR 개발은 처음엔 복잡해 보이지만, 한 번 기본기를 잡으면 정말 재미있어! 내가 만든 3D 오브젝트가 현실 공간에 나타나는 순간의 그 짜릿함은 다른 개발에서 느끼기 어려운 특별한 경험이야. ar_flutter_plugin으로 시작해서 점점 더 복잡한 AR 경험을 만들어나가다 보면, 어느새 AR 전문 개발자가 되어있을 거야! 🚀
ar_flutter_plugin 핵심 요약 ⚙️ 설치 및 설정 pubspec + 네이티브 설정 🎛️ 4개 매니저 시스템 Session/Object/Anchor/Location 🧊 GLB/GLTF 3D 모델 웹 URL 또는 로컬 에셋 🗺️ 평면 감지 + 히트 테스트 수평/수직 평면 인식 👆 인터랙션 탭/드래그/회전 처리 ☁️ Cloud Anchors 멀티 기기 AR 공유 Flutter + ARCore + ARKit = 크로스 플랫폼 AR 앱 🚀
댓글 작성

이 글에 대한 여러분의 생각을 들려주세요

댓글 0
댓글을 불러오는 중입니다.

아직 댓글이 없습니다.