13 KiB

Raw Permalink Blame History

Explore Lumajang AR - Complete AR Implementation

Project Overview

Complete Augmented Reality (AR) feature implementation for Flutter tourism application "Explore Lumajang AR" using markerless AR with surface detection (ARCore).

🎯 Key Features

✅ Surface Detection: Automatic detection of flat surfaces for object placement
✅ 3D Object Placement: Place tourism destination 3D models on detected surfaces
✅ Gesture Controls:
- Pan to rotate objects
- Pinch to zoom/scale
- Drag to move position
✅ Object Manipulation: Rotate, scale, move, reset, and delete objects
✅ Real-time Visualization: Smooth object rendering and transformation
✅ Modern UI: Material 3 design with intuitive controls
✅ Clean Architecture: Well-structured, maintainable code
✅ Performance Optimized: Mobile-friendly implementation

📁 Project Structure

android/wisata_app/
├── lib/
│   ├── main.dart                          # App entry point
│   ├── models/
│   │   ├── app_user.dart                  # User model
│   │   ├── destination.dart               # Destination model (UPDATED with AR fields)
│   │   ├── ar_object.dart                 # ✨ NEW: 3D object model
│   │   ├── ar_plane.dart                  # ✨ NEW: Surface plane model
│   │   └── ar_scene.dart                  # ✨ NEW: Scene state model
│   ├── pages/
│   ├── screens/
│   │   ├── splash_screen.dart             # Splash screen
│   │   ├── login_screen.dart              # Login screen
│   │   ├── register_screen.dart           # Register screen
│   │   ├── forgot_password_screen.dart    # Forgot password screen
│   │   ├── dashboard_screen.dart          # Dashboard (destinations list)
│   │   ├── home_screen.dart               # Home screen
│   │   ├── detail_destination_screen.dart # Destination details
│   │   └── ar_view_screen.dart            # ✨ UPDATED: Full AR implementation
│   ├── services/
│   │   ├── auth_service.dart              # Authentication service
│   │   ├── destination_service.dart       # UPDATED with AR model paths
│   │   ├── ar_service.dart                # ✨ NEW: AR state management
│   │   ├── ar_utils.dart                  # ✨ NEW: AR utilities
│   │   └── ar_extensions.dart             # ✨ NEW: AR extensions & examples
│   ├── widgets/
│   │   ├── info_card.dart
│   │   └── primary_button.dart
│   └── main.dart
├── assets/
│   ├── images/                            # Destination images
│   └── models/                            # ✨ 3D model files (GLB/GLTF)
│       ├── waterfall.glb
│       ├── mountain.glb
│       ├── lake.glb
│       ├── waterfall2.glb
│       ├── village.glb
│       └── README.md                      # Model setup guide
├── android/
│   ├── app/
│   │   └── src/main/AndroidManifest.xml  # ✨ UPDATED with AR permissions
│   ├── build.gradle
│   └── gradle.properties
├── pubspec.yaml                           # ✨ UPDATED with AR dependencies
├── AR_IMPLEMENTATION_GUIDE.md             # ✨ NEW: Detailed technical guide
├── AR_QUICKSTART.md                       # ✨ NEW: Quick start guide
└── README.md                              # This file

🚀 Getting Started

Prerequisites

Flutter 3.6.2+
Dart 3.6.2+
Android API 21+ (for ARCore)
Google Play Services installed on test device

Installation

Navigate to project:
```
cd android/wisata_app
```
Install dependencies:
```
flutter pub get
```
Run the app:
```
flutter run
```

Quick AR Test

Launch app → Login
Navigate to Dashboard
Select a destination
Tap "View in Augmented Reality"
Move phone to detect surfaces
Tap "Place Object"
Use controls to manipulate object

📦 Dependencies Added

ar_flutter_plugin: ^0.7.3    # AR functionality
vector_math: ^2.1.4           # 3D math operations
provider: ^6.4.0              # State management

🏗️ Architecture

Layer Structure

┌─────────────────────────────────┐
│     UI Layer (Screens)          │
│  ar_view_screen.dart            │
└────────────┬────────────────────┘
             │
┌────────────▼────────────────────┐
│   Business Logic (Services)     │
│  ar_service.dart                │
│  ar_utils.dart                  │
└────────────┬────────────────────┘
             │
┌────────────▼────────────────────┐
│    Data Layer (Models)          │
│  ar_scene.dart                  │
│  ar_object.dart                 │
│  ar_plane.dart                  │
└────────────┬────────────────────┘
             │
┌────────────▼────────────────────┐
│  ar_flutter_plugin (AR Engine)  │
│  ARCore Integration             │
└─────────────────────────────────┘

State Management

ChangeNotifier Pattern: ArService extends ChangeNotifier
ListenableBuilder: UI rebuilds when service notifies
Reactive Updates: All transformations trigger notifications

🎮 User Flow

App Launch
    ↓
Authentication (Login/Register)
    ↓
Dashboard (View Destinations)
    ↓
Detail Destination (View destination info)
    ↓
AR View Screen (AR Mode)
    ├─→ Surface Detection (Phone movement)
    ├─→ Place Object (User tap)
    ├─→ Gestures:
    │   ├─ Rotate (Pan)
    │   ├─ Scale (Pinch)
    │   └─ Move (Drag)
    └─→ Manipulation:
        ├─ Rotate Button
        ├─ Zoom In/Out Buttons
        ├─ Reset Button
        └─ Delete Button

🎨 UI Components

AR View Screen States

Scanning State
- Shows scanner animation
- Displays "Scanning for surfaces..."
- Prompts "Move your phone slowly"
Placing State
- Shows detected plane
- Displays "Ready to place object"
- Enable Place Object button
Placed State
- Shows 3D model visualization
- Displays manipulation controls
- Shows status bar (planes, objects count)

Controls

Element	Function
Back Button	Return to destination detail
Place Object	Add 3D model to scene
Rotate	Spin around Y-axis
Zoom In	Increase scale (×1.2)
Zoom Out	Decrease scale (÷1.2)
Reset	Return to initial state
Delete	Remove all objects

🔧 Configuration

Android Setup

AndroidManifest.xml (already configured):

<uses-permission android:name="android.permission.CAMERA" />
<uses-feature android:name="android.hardware.camera.ar" android:required="true" />
<meta-data android:name="com.google.ar.core" android:value="required" />

Permissions

Camera: Required for AR functionality
Location (optional): For enhanced context

Minimum Requirements

API Level: 21+
Target API: 33+
ARCore Support: Required

📋 Core Classes

ArService

Main service managing AR scene and operations.

final arService = ArService(destination: destination);
arService.placeObject(objectId, modelPath, objectName);
arService.rotateObject(angle);
arService.zoomIn();

ArObject

Represents a 3D object in AR space.

ArObject(
  id: 'unique_id',
  modelPath: 'assets/models/model.glb',
  name: 'Object Name',
  position: Vector3(0, 0, 0),
  rotation: Vector3(0, 0, 0),
  scale: 1.0,
)

ArPlane

Represents a detected surface.

ArPlane(
  id: 'plane_1',
  center: Vector3(0, 0, -2),
  normal: Vector3(0, 1, 0),
  extent: Vector2(3, 3),
  type: 'horizontal_up',
)

ArScene

Manages complete AR scene state.

arScene.addObject(arObject);
arScene.addPlane(arPlane);
arScene.selectObject(objectId);
arScene.clearScene();

🎯 Integration Points

Adding Destinations to AR

Update destination_service.dart:

arModelPath: 'assets/models/model.glb',
arDescription: 'Model description',

Add 3D model to assets/models/
Update pubspec.yaml:
```
assets:
  - assets/models/model.glb
```

Customizing AR Experience

Modify gesture sensitivity in ar_view_screen.dart
Adjust object scaling ranges in ar_object.dart
Customize UI colors and animations in ar_view_screen.dart

🧪 Testing

Manual Testing Checklist

App launches without crashes
Camera permission requested
Surfaces detected when phone moves
Objects placed on detected planes
Objects rotate with pan gesture
Objects scale with pinch gesture
Control buttons responsive
Objects deletable
Scene clearable
Back navigation works

Unit Testing Example

test('ArObject position update', () {
  final obj = ArObject(
    id: 'test',
    modelPath: 'path',
    name: 'Test',
  );
  
  obj.updatePosition(Vector3(1, 2, 3));
  expect(obj.position, Vector3(1, 2, 3));
});

🚦 Performance Tips

Polygon Count: Keep models under 50k triangles
Texture Size: Use 1K or 2K maximum
Material Count: Minimal materials per model
Object Limit: 1-2 objects per scene
Frame Rate: Target 30+ FPS on mobile
Memory: Monitor allocation with DevTools

📚 Documentation Files

AR_IMPLEMENTATION_GUIDE.md: Complete technical reference
AR_QUICKSTART.md: 5-minute quick start
assets/models/README.md: 3D model setup guide
Code Comments: Extensive inline documentation

🔍 Troubleshooting

Surfaces Not Detected

Ensure good lighting
Move phone slowly and deliberately
Try different surface textures
Check device has ARCore installed

Objects Not Appearing

Verify model file path
Check GLB file integrity
Ensure model in assets directory
Check console for errors

Performance Issues

Reduce model complexity
Limit simultaneous objects
Compress textures
Monitor with Performance DevTools

Camera Permission Denied

Grant permission in app settings
Uninstall and reinstall app
Clear app cache

🚀 Future Enhancements

Multiple simultaneous objects
Physics-based interactions
Object animations
Collision detection
Lighting controls
Screenshot/video capture
Shareable AR experiences
Cloud model streaming
Multi-user AR
Persistent AR anchors

📖 Advanced Topics

Custom Animations

extension on ArObject {
  Future<void> animateToPosition(Vector3 target, Duration duration) async {
    // Implementation in ar_extensions.dart
  }
}

Physics Integration

class ArPhysicsObject {
  void applyForce(Vector3 force) { ... }
  void update(double deltaTime) { ... }
}

Collision Detection

ArCollisionDetector.checkSphereSphereCollision(obj1, r1, obj2, r2);
ArCollisionDetector.checkSpherePlaneCollision(obj, r, plane);

📞 Support

Issues: Check Troubleshooting section
Questions: Review documentation files
API Docs: Code comments in service files
Examples: See ar_extensions.dart

📄 License

This AR implementation is part of the Explore Lumajang AR tourism application.

🎓 Learning Resources

✅ Checklist for Deployment

All dependencies installed and versions compatible
Android permissions configured
3D models optimized and tested
AR service thoroughly tested
UI responsive on target devices
Performance acceptable (30+ FPS)
Error handling implemented
Documentation complete
Code commented
Ready for production

Version: 1.0.0
Last Updated: 2026-05-15
Status: ✅ Complete and Ready for Production

13 KiB Raw Permalink Blame History Unescape Escape