orang-sukses

docs: update badge and prerequisites for Hugging Face

e9f0525 2 months ago

6.35 kB

	# ♻️ 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.