🖐️ Real-Time Hand Tracking dengan MediaPipe & OpenCV

Project ini merupakan modul Real-Time Hand Tracking berbasis Python yang memanfaatkan MediaPipe Hands dan OpenCV. Dirancang secara modular dengan class HandDetector sehingga sangat mudah di-import dan diintegrasikan ke berbagai project Computer Vision lanjutan.

---

📋 Daftar Isi

1. Kemampuan & Fitur Utama
2. Peta 21 Landmark Tangan
3. Instalasi & Persyaratan
4. Cara Menjalankan
5. Dokumentasi API (HandDetector)
6. Ide & Potensi Pengembangan Lanjutan

---

✨ Kemampuan & Fitur Utama

Project ini memiliki kemampuan dasar berikut secara real-time:

1. Deteksi Multi-Tangan: Mampu mendeteksi hingga 2 tangan sekaligus (dapat disesuaikan parameter max_hands).
2. Pelacakan 21 Titik Landmark: Melacak koordinat 3D $(X, Y, Z)$ dari 21 sendi tangan manusia secara presisi.
3. Visualisasi Rangka (Skeleton): Menggambar garis penghubung antar-sendi tangan (HAND_CONNECTIONS) pada feed video.
4. Konversi Koordinat Pixel Real-Time: Mengubah koordinat rasio normalisasi MediaPipe (0.0 - 1.0) menjadi koordinat piksel layar $(X, Y)$.
5. Indikator FPS Real-Time: Menampilkan jumlah Frame Per Second di layar untuk memantau performa sistem.

---

🖐️ Peta 21 Landmark Tangan

MediaPipe memetakan setiap tangan menjadi 21 titik landmark dengan ID khusus:

       8      12     16     20
       |      |      |      |
       7      11     15     19
       |      |      |      |
   4   6      10     14     18
   |   |      |      |      |
   3   5------9------13-----17
   |  /
   2 /
  / /
 1 /
 |/
 0 (Pergelangan / Wrist)

ID	Nama Landmark	Keterangan
0	WRIST	Pergelangan tangan
1 - 4	THUMB	1: CMC, 2: MCP, 3: IP, 4: Ujung Ibu Jari (TIP)
5 - 8	INDEX_FINGER	5: MCP, 6: PIP, 7: DIP, 8: Ujung Jari Telunjuk (TIP)
9 - 12	MIDDLE_FINGER	9: MCP, 10: PIP, 11: DIP, 12: Ujung Jari Tengah (TIP)
13 - 16	RING_FINGER	13: MCP, 14: PIP, 15: DIP, 16: Ujung Jari Manis (TIP)
17 - 20	PINKY	17: MCP, 18: PIP, 19: DIP, 20: Ujung Jari Kelingking (TIP)

---

🛠️ Instalasi & Persyaratan

• Python: Versi 3.8 - 3.11
• Kamera: Webcam Laptop / External USB Camera

Instal seluruh library yang dibutuhkan dengan menjalankan:

pip install -r requirements.txt

---

🚀 Cara Menjalankan

1. Skrip Real-Time Hand Tracking Dasar

Jalankan skrip utama main.py:

python3 main.py

2. 🎮 Game Batu-Gunting-Kertas (Rock-Paper-Scissors) Real-Time

Jalankan game interaktif game_rps.py:

python3 game_rps.py

• Tekan s untuk memulai hitung mundur (3... 2... 1...) dan adu gestur dengan AI.
• Tekan r untuk mereset skor (Pemain vs AI).
• Tekan q untuk keluar dari game.

Catatan Pengguna macOS: Jika webcam tidak terbuka, pastikan izin kamera diaktifkan di System Settings ➔ Privacy & Security ➔ Camera untuk aplikasi Terminal / IDE Anda.

---

🧩 Dokumentasi API (HandDetector)

Skrip hand_detector.py menyediakan class modular yang siap dipakai di project lain:

1. Inisialisasi Class

from hand_detector import HandDetector

detector = HandDetector(
    mode=False,        # False untuk video stream, True untuk gambar diam
    max_hands=2,       # Jumlah maksimal tangan yang dideteksi
    detection_con=0.5, # Minimal confidence deteksi awal (0.0 - 1.0)
    track_con=0.5      # Minimal confidence penelusuran (0.0 - 1.0)
)

2. Method find_hands(img, draw=True)

Mendeteksi tangan dan menggambar rangka jika draw=True.

img = detector.find_hands(img, draw=True)

3. Method find_position(img, hand_no=0, draw=True)

Mengembalikan daftar koordinat [[id, x, y], ...] untuk 21 landmark tangan ke-hand_no.

lm_list = detector.find_position(img, draw=False)
if len(lm_list) != 0:
    # Koordinat ujung jari telunjuk (ID 8)
    id_8, x_telunjuk, y_telunjuk = lm_list[8]
    print(f"Telunjuk di X:{x_telunjuk}, Y:{y_telunjuk}")

4. Method get_handedness(hand_no=0)

Mengembalikan label jenis tangan ('Left' atau 'Right').

hand_type = detector.get_handedness(hand_no=0)

5. Method fingers_up(lm_list, hand_type="Right")

Menentukan 5 posisi jari mana saja yang sedang terbuka (1) atau tertutup (0).

fingers = detector.fingers_up(lm_list, hand_type=hand_type)
# Contoh Output: [0, 1, 1, 0, 0] -> Ibu Jari & Manis & Kelingking tertutup, Telunjuk & Tengah terbuka

---

💡 Ide & Potensi Pengembangan Lanjutan

Dengan modul tracking ini, Anda dapat membangun berbagai aplikasi canggih seperti:

1. 🖱️ Virtual Mouse / Air Mouse

   • Mengontrol kursor mouse laptop di udara dengan menggerakkan jari telunjuk (ID 8), dan melakukan klik saat jari telunjuk & ibu jari ditempelkan (pinch).

2. 🎨 Virtual Painter (Melukis di Udara)

   • Menggambar pada kanvas digital di layar menggunakan gerakan jari telunjuk sebagai kuas dan telunjuk+tengah sebagai penghapus.

3. 🔊 Gesture Volume & Brightness Controller

   • Mengukur jarak Euclidean antara Ujung Ibu Jari (ID 4) dan Ujung Telunjuk (ID 8) dengan fungsi math.hypot() untuk mengatur level volume sistem suara atau kecerahan layar.

4. 🖐️ Finger Counter (Penghitung Jari)

   • Mendeteksi berapa jumlah jari yang sedang berdiri dengan membandingkan koordinat Y ujung jari (ID 8, 12, 16, 20) terhadap sendi di bawahnya (ID 6, 10, 14, 18).

5. 🎮 Hand Gesture Controller untuk Game

   • Mengontrol karakter game (seperti Flappy Bird, Snake, Car Racing) menggunakan gerakan tangan atau gestur membuka/menutup telapak tangan.

6. 🤟 Penerjemah Bahasa Isyarat (Sign Language Translator)

   • Mengklasifikasikan pola 21 landmark menggunakan Machine Learning / KNN / Neural Network untuk mengenali alfabet bahasa isyarat (SIBI / BISINDO / ASL).

7. 👈 Gesture Media Control (Play/Pause/Skip)

   • Mengubah lagu atau slide presentasi PowerPoint dengan mengusap tangan ke kiri/kanan.