# Palm Oil Ripeness AI - Mobile App

A professional, high-performance Flutter application designed for palm oil plantation managers and harvesters. This app provides real-time and static AI-driven ripeness detection, enabling data-driven harvesting decisions directly in the field.

---

## 📱 Executive Summary
The **Palm Oil Ripeness AI** mobile app is a field-ready tool that automates the assessment of Fresh Fruit Bunches (FFB). By leveraging on-device Deep Learning (TFLite), the app eliminates the need for internet connectivity in remote plantations, providing instant grading and health alerts to optimize yield and minimize loss from premature harvest.

---

## 🛠 Features

### 1. **Live Inference (Point-and-Scan)**
- **Real-time Detection:** Utilizes an atomic idle-lock mechanism to process camera streams at high speed.
- **Momentum Lock:** A robust hysteresis system that "locks" onto fruit bunches to prevent camera stutter and ensure reliable capture.
- **Auto-Capture:** Automatically triggers a high-resolution snapshot once a stable detection is confirmed.

### 2. **Snap & Analyze (Manager's Manual Mode)**
- **High-Res Accuracy:** Manual shutter mode using `ResolutionPreset.high` for maximum detail.
- **Direct JPEG Decoding:** Skips YUV conversion for the most accurate industrial-grade inference.
- **Auto-Reset Workflow:** Seamlessly clears previous results after acknowledgment to allow rapid sequential captures.

### 3. **Analyze Gallery**
- Allows managers to analyze previously captured photos from the device's storage.
- Includes a scanning animation and detailed bounding box overlays.

### 4. **History Vault & Result Persistence**
- **SQLite Storage:** Every analysis is stored locally with metadata (ripeness class, confidence, coordinates).
- **Image Archiving:** Automatically copies and persists captured images to the `ApplicationDocumentsDirectory`.

### 5. **Industrial Alerts & Summaries**
- **Health Alert:** 🔴 Red warnings for "Abnormal" or "Empty_Bunch" detections.
- **Yield Warning:** 🟠 Orange alerts for "Unripe" or "Underripe" fruit, highlighting "Potential Yield Loss".

---

## 🚀 Setup & Installation

### Prerequisites
- [Flutter SDK](https://docs.flutter.dev/get-started/install) (latest stable).
- Android Studio / VS Code with Flutter & Dart extensions.
- A physical Android/iOS device (Camera required; Emulators NOT recommended).

### 1. Initialize Project
```bash
# Navigate to the mobile project directory
cd palm_oil_mobile

# Fetch dependencies
flutter pub get
```

### 2. Run the App
To achieve real-time performance, it is **highly recommended** to run in **Release Mode**:
```bash
flutter run --release
```

---

## 🏗 Project Architecture

### 📁 `lib/screens/` (UI Layer)
- **`home_screen.dart`**: Central navigation hub with card-based dashboard.
- **`live_analysis_screen.dart`**: Advanced camera stream handler with momentum locking logic.
- **`static_capture_screen.dart`**: Dedicated manual capture workflow with industrial summaries.
- **`analysis_screen.dart`**: Gallery-based interface with scanning overlays.
- **`history_screen.dart`**: Secure vault for reviewing past palm records.

### 📁 `lib/services/` (Logic Layer)
- **`tflite_service.dart`**: A persistent Isolate-based service that handles all AI inference (static and stream-based) without blocking the UI thread.
- **`database_helper.dart`**: Manages the local SQLite database for perpetual history.

### 📁 `lib/models/` (Data Layer)
- **`palm_record.dart`**: Schema definition for detection history and bounding box coordinates.

---

## 📦 Assets
- `assets/best.tflite`: The YOLO-based ripeness detection model.
- `assets/labels.txt`: Class definitions (Ripe, Unripe, Underripe, Overripe, Abnormal, Empty_Bunch).

---

## ⚠️ Requirements & Permissions
- **Camera:** Required for Live and Static analysis.
- **Storage:** Required to save/load photos and database records.