🏠 flutter_roomplan

Seamlessly integrate Apple's RoomPlan SDK into your Flutter apps
Capture accurate 3D room scans using ARKit with this powerful plugin. Perfect for AR measurement, smart home, and interior design solutions.

---

⚠️ Requirements

• iOS 16.0+ (for single room scanning)
• iOS 17.0+ (for multi-room merge support)
• ARKit-compatible device:
  iPhone 12 or later, or recent iPad Pro
• LiDAR Scanner required for room scanning functionality

---

📌 Key Features

• 📸 Launches native RoomCaptureViewController for full-screen AR scanning
• 🪄 Captures room geometry + objects as structured JSON
• 🔗 Simple Flutter API to start scans and handle results
• 🚀 Returns complete CapturedRoom JSON specification
• 📱 Device compatibility checking
• 📦 USDZ file export support
• 📜 JSON file export support for room data and metadata
• 🏘️ Multi-room merge support (iOS 17.0+) for scanning and combining multiple rooms

---

🔍 Data Structure

The following diagram shows the structure of the captured room data:

The green nodes indicate updates from WWDC 2023 (iOS 17)

---

🚀 Quick Start

1️⃣ Installation

Add to pubspec.yaml:

dependencies:
  flutter_roomplan: latest_version

Add the necessary NSCameraUsageDescription key to your ios/Runner/Info.plist file, explaining the reason for camera access:

<key>NSCameraUsageDescription</key>
<string>The camera is required to scan your room and generate a 3D model.</string>

2️⃣ Basic Usage

import 'package:flutter_roomplan/flutter_roomplan.dart';

// Create plugin instance
final roomPlan = FlutterRoomplan();

// Check if device supports RoomPlan
final isSupported = await roomPlan.isSupported();
final isMultiRoomSupported = await roomPlan.isMultiRoomSupported();

// Register callback for scan results
roomPlan.onRoomCaptureFinished(() async {
  print('Room scan completed');
  // Get file paths after scan
  final usdzPath = await roomPlan.getUsdzFilePath();
  final jsonPath = await roomPlan.getJsonFilePath();
  print('USDZ: $usdzPath');
  print('JSON: $jsonPath');
});

// Start single room scanning
try {
  await roomPlan.startScan();
} catch (e) {
  print('Error starting scan: $e');
}

// Start multi-room scanning (iOS 17.0+)
try {
  await roomPlan.startScan(enableMultiRoom: true);
} catch (e) {
  print('Error starting multi-room scan: $e');
}

3️⃣ Available Methods

• isSupported(): Check if the device supports RoomPlan (iOS 16.0+)
• isMultiRoomSupported(): Check if the device supports multi-room merge (iOS 17.0+)
• startScan(): Launch single room scanning interface
• startScan(enableMultiRoom: true): Launch multi-room merge scanning (iOS 17.0+)
• onRoomCaptureFinished(): Register callback for scan results
• getUsdzFilePath(): Get path to exported USDZ file from last scan
• getJsonFilePath(): Get path to exported JSON file from last scan

4️⃣ Error Handling

The plugin throws exceptions for common errors:

• Device not supported
• Required permissions not granted
• Scan initialization failures

Always wrap startScan() in a try-catch block and check device support before scanning.

---

📝 Example

Check out the example app for a complete implementation showing:

• Device support checking
• Multi-room support detection
• Single room scanning
• Multi-room merge scanning (iOS 17.0+)
• Result handling
• USDZ file path retrieval
• JSON file path retrieval
• Error management

---

⚠️ Limitations

Multiple Rooms Scanning

• Multi-room merge support available on iOS 17.0+ devices
• Single room scanning supported on iOS 16.0+
• Can produce inaccurate data during extended scanning sessions
• Device may experience overheating on longer scans
• Best practice: For iOS 16 devices, scan one room at a time with cooling breaks between scans

Surface Shape Detection

• Limited to rectangular and square surface detection
• Cannot accurately detect curved edges or irregular shapes
• Assumes all surfaces are planar with right angles

Phantom Object Detection

• May occasionally detect non-existent objects
• Can produce false positives in complex lighting conditions
• Recommend verifying critical measurements manually

Object Detection Limits

• Currently restricted to 16 types of household objects
• Limited to common furniture and fixture categories
• May not recognize specialized or custom furniture pieces

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.