# ♻️ KomposIn

[![Hugging Face](https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-Repository-orange)](https://huggingface.co/KomposIn-Team/fpAI-komposin)

KomposIn adalah aplikasi cerdas berbasis *Computer Vision* (YOLOv26-seg) dan web (Next.js) yang dirancang untuk mengklasifikasikan berbagai jenis sampah (Organik, Anorganik, B3, dan Residu) secara *real-time*. Selain itu, aplikasi ini juga dilengkapi dengan antarmuka web interaktif yang menampilkan simulasi 3D.

Project ini terdiri dari 2 bagian utama:
- **Backend (`be/`)**: API berbasis Python (FastAPI) yang memproses gambar/kamera menggunakan model Ultralytics YOLO.
- **Frontend (`fe/`)**: Aplikasi web interaktif berbasis Next.js (React), menggunakan 3D rendering (Three.js), dan Framer Motion.
- **Model (`model/`)**: Penyimpanan model AI (YOLO) terlatih untuk segmentasi sampah.

---

## Persyaratan Sistem (Prerequisites)

Pastikan Anda telah menginstal perangkat lunak berikut di komputer Anda:
- **Python 3.8+**
- **Node.js 18+** dan **npm**
- **Git** & **Git LFS** (Wajib terinstal untuk mengunduh model AI dari Hugging Face)

---

## 1. Menjalankan Backend (FastAPI + YOLO)

Backend berfungsi untuk memproses gambar da webcam/file dan memberikan hasil prediksi klasifikasi sampah.

### Langkah-langkah:
1. Buka terminal baru dan arahkan ke folder `be`:
   ```bash
   cd be
   ```
2. Buat *Virtual Environment* (direkomendasikan) agar dependensi Python tidak bentrok:
   ```bash
   python -m venv venv
   ```
3. Aktifkan *Virtual Environment*:
   - **Windows:** `.\venv\Scripts\activate`
   - **Mac/Linux:** `source venv/bin/activate`
4. Instal semua dependensi yang dibutuhkan:
   ```bash
   pip install -r requirements.txt
   ```
5. Jalankan server FastAPI:
   ```bash
   uvicorn main:app --reload
   ```
6. Backend akan berjalan di `http://localhost:8000`. Anda juga bisa melihat dokumentasi API di `http://localhost:8000/docs`.

---

## 2. Menjalankan Frontend (Next.js)

Frontend berfungsi sebagai antarmuka pengguna (UI) yang menampilkan visual interaktif, simulasi 3D, dan integrasi webcam ke backend.

### Langkah-langkah:
1. Buka terminal baru (biarkan terminal Backend tetap menyala), lalu arahkan ke folder `fe`:
   ```bash
   cd fe
   ```
2. Instal semua dependensi Node.js:
   ```bash
   npm install
   ```
3. Jalankan server *development*:
   ```bash
   npm run dev
   ```
4. Frontend akan berjalan di `http://localhost:3000`. Buka URL tersebut di browser Anda untuk menggunakan aplikasi KomposIn.

---

## Struktur Folder Utama

```text
fpAI3/
├── be/                 # Backend FastAPI
│   ├── main.py         # Entry point API dan logika inferensi YOLO
│   └── requirements.txt# Daftar dependensi Python
├── fe/                 # Frontend Next.js
│   ├── app/            # Next.js App Router (Halaman dan Layout)
│   ├── components/     # Komponen React (Simulasi 3D, UI, dll)
│   └── package.json    # Daftar dependensi Node.js
└── model/              # Direktori Model YOLO
    └── waste_segmentor_yolo26/
        └── waste_yolo26seg_best.pt  # Model terlatih
```

## 🛠️ Tech Stack & Teknologi yang Digunakan

Aplikasi KomposIn dibangun menggunakan arsitektur modern yang memisahkan antara *Frontend*, *Backend*, dan *Machine Learning*:

### 🧠 Model & AI (Artificial Intelligence)
- **Ultralytics YOLO (v8/v26-seg)**: Model *Computer Vision* (segmentasi) yang digunakan untuk mendeteksi dan mengklasifikasi objek sampah (Organik, Anorganik, B3, Residu) secara *real-time*.
- **OpenCV (`cv2`)**: Digunakan untuk pemrosesan gambar (decoding dari *byte stream* ke format matriks gambar, anotasi *bounding box*, dan *encoding* kembali ke Base64).
- **NumPy**: Digunakan untuk komputasi matriks yang cepat pada data gambar.

### ⚙️ Backend (API Server)
- **Python (3.8+)**: Bahasa pemrograman utama untuk inferensi model AI.
- **FastAPI**: Framework web Python modern dan sangat cepat, digunakan sebagai REST API endpoint untuk menerima *frame* kamera dan mengembalikan hasil deteksi.
- **Uvicorn**: Server ASGI (*Asynchronous Server Gateway Interface*) berkinerja tinggi untuk menjalankan aplikasi FastAPI.

### 🎨 Frontend (Web UI)
- **Next.js (v16) & React (v19)**: Framework *frontend* modern untuk membangun antarmuka pengguna yang responsif.
- **TailwindCSS (v4)**: Framework CSS *utility-first* untuk penataan gaya (styling) yang rapi, *modern*, dan responsif tanpa perlu menulis kode CSS dari awal.
- **Framer Motion**: Library animasi React untuk memberikan transisi yang sangat halus dan interaksi dinamis pada *dashboard* pengguna.

### 🧊 3D Engine & Multimedia
- **Three.js & React Three Fiber (R3F)**: Engine WebGL dan integrasi React-nya untuk membuat dan merender grafis serta simulasi 3D interaktif di browser.
- **React Three Drei**: Koleksi *helper* dan abstrak komponen (seperti kontrol kamera, *lighting*, dan model 3D loader) untuk mempermudah pengembangan React Three Fiber.
- **React Webcam**: Komponen untuk mengakses kamera (webcam) pengguna melalui browser dan mengirim *frame* secara langsung ke API backend.

---

## 🚀 Cara Update Code ke Hugging Face (Push & Pull)

Karena project ini memiliki file model dan gambar yang sangat besar, kita menggunakan **Git LFS** dan menyimpannya di repository **Hugging Face**. Berikut adalah panduan singkat untuk berkolaborasi:

### ⬇️ Mengambil Perubahan Terbaru (Pull)
Jika rekan satu tim Anda baru saja meng-update kode, Anda wajib menarik/mengambil perubahan tersebut ke laptop Anda terlebih dahulu sebelum mulai menulis kode baru:
```bash
git pull hf main
```

### ⬆️ Menyimpan Perubahan (Push)
Setiap kali Anda selesai mengubah kode (misal: mengedit desain frontend atau logika backend) dan ingin menyimpannya ke repository bersama:

1. **Masukkan semua perubahan:**
   ```bash
   git add .
   ```
2. **Beri label/keterangan apa yang Anda ubah:**
   ```bash
   git commit -m "Penjelasan singkat fitur yang diubah"
   ```
3. **Kirim ke server Hugging Face:**
   ```bash
   git push hf main
   ```

> **⚠️ Penting:** Saat Anda melakukan `git push`, jika Git meminta password, Anda **TIDAK BOLEH** memasukkan password akun Hugging Face. Anda wajib menggunakan **Access Token** yang memiliki hak akses **Write**. Token ini bisa dibuat di menu *Settings* akun Hugging Face masing-masing.