# Instrukcja Obsługi - Program Transformacji i Detekcji Obrazów

## Spis treści
1. [Uruchomienie programu](#uruchomienie-programu)
2. [Wybór źródła obrazu](#wybór-źródła-obrazu)
3. [Menu główne](#menu-główne)
4. [Opis transformacji](#opis-transformacji)
5. [Detekcja obiektów YOLO](#detekcja-obiektów-yolo)
6. [Skróty klawiszowe](#skróty-klawiszowe)
7. [Rozwiązywanie problemów](#rozwiązywanie-problemów)

---

## Uruchomienie programu

### Krok 1: Instalacja zależności (jednorazowo)
```bash
cd C:\Praca\ProjektyPython\2025_11_elektryk\dzien_02
pip install -r requirements.txt
```

### Krok 2: Uruchomienie
```bash
python test_transform.py
```

---

## Wybór źródła obrazu

Po uruchomieniu programu zobaczysz menu wyboru źródła obrazu:

```
WYBÓR ŹRÓDŁA OBRAZU
============================================================
1. Wybierz plik z dysku (okno dialogowe)
2. Podaj URL do obrazu w internecie
3. Użyj domyślnego obrazu z katalogu dzien_01
0. Anuluj
============================================================
```

### Opcja 1: Plik z dysku
- Otwiera okno dialogowe do wyboru pliku
- Obsługuje formaty: JPG, JPEG, PNG, BMP, GIF, TIFF
- Możesz wybrać dowolny obraz z komputera

### Opcja 2: URL z internetu
- Wpisz adres URL obrazu (np. z Unsplash, Pixabay)
- Przykład: `https://picsum.photos/800/600`
- Obraz zostanie pobrany i zapisany tymczasowo

### Opcja 3: Domyślny obraz
- Używa pierwszego obrazu z katalogu `dzien_01`
- Szybka opcja do testowania

---

## Menu główne

Po wyborze obrazu zobaczysz menu z 18 dostępnymi transformacjami:

```
DOSTĘPNE TRANSFORMACJE OBRAZU
============================================================
 1. GRAY
 2. BLUR_GAUSSIAN
 3. BLUR_MEDIAN
 4. BLUR_BILATERAL
 5. CANNY
 6. EDGE_DETECTION
 7. THRESHOLD
 8. ADAPTIVE
 9. SOBEL
10. LAPLACIAN
11. CONTOURS
12. FACE_DETECTION
13. SHARPEN
14. EMBOSS
15. YOLO_DETECT
16. YOLO_DETECT_MEDIUM
17. YOLO_DETECT_LARGE
18. YOLO_SEGMENT
------------------------------------------------------------
 C. Zmień obraz (wybierz inny plik)
 0. Wyjście z programu
============================================================
```

### Jak używać:
1. Wpisz numer transformacji (1-18)
2. Naciśnij ENTER
3. Poczekaj na przetworzenie obrazu
4. Zobaczysz okno z porównaniem: **Oryginalny obraz | Przetworzony obraz**
5. Naciśnij dowolny klawisz w oknie obrazu, aby zamknąć
6. Naciśnij ENTER w konsoli, aby wrócić do menu
7. Wybierz kolejną transformację lub '0' aby zakończyć

---

## Opis transformacji

### 1. GRAY - Skala szarości
**Co robi:** Konwertuje kolorowy obraz do skali szarości (czarno-biały).

**Zastosowanie:**
- Uproszczenie obrazu
- Przygotowanie do dalszego przetwarzania
- Redukcja ilości danych

**Przykład użycia:** Analiza tekstur, detekcja krawędzi

---

### 2. BLUR_GAUSSIAN - Rozmycie Gaussa
**Co robi:** Rozmywa obraz używając filtru Gaussa (jądro 15x15).

**Zastosowanie:**
- Redukcja szumu
- Wygładzenie obrazu
- Usunięcie drobnych szczegółów

**Parametry:** Rozmiar jądra 15x15 pikseli

**Przykład użycia:** Przygotowanie obrazu przed detekcją krawędzi

---

### 3. BLUR_MEDIAN - Rozmycie medianowe
**Co robi:** Rozmywa obraz używając filtru medianowego.

**Zastosowanie:**
- Usuwanie szumu typu "sól i pieprz"
- Zachowanie krawędzi lepiej niż Gaussian
- Wygładzenie obrazu

**Przykład użycia:** Czyszczenie zaszumionych zdjęć

---

### 4. BLUR_BILATERAL - Rozmycie bilateralne
**Co robi:** Rozmywa obraz zachowując ostre krawędzie.

**Zastosowanie:**
- Redukcja szumu z zachowaniem szczegółów
- Efekt "wygładzenia skóry" w fotografii
- Przygotowanie do segmentacji

**Zaleta:** Nie rozmywa krawędzi obiektów

---

### 5. CANNY - Detekcja krawędzi Canny
**Co robi:** Wykrywa krawędzie w obrazie metodą Canny'ego.

**Zastosowanie:**
- Detekcja konturów obiektów
- Analiza kształtów
- Segmentacja obrazu

**Parametry:** Progi 100 i 200

**Wynik:** Biały obraz z czarnymi krawędziami

---

### 6. EDGE_DETECTION - Zaawansowana detekcja krawędzi
**Co robi:** Wykrywa krawędzie z wcześniejszym rozmyciem Gaussa.

**Zastosowanie:**
- Detekcja krawędzi z redukcją szumu
- Lepsza jakość niż zwykły Canny
- Analiza struktury obrazu

**Parametry:** Gaussian blur (5x5), Canny (50, 150)

---

### 7. THRESHOLD - Progowanie binarne
**Co robi:** Konwertuje obraz do czarno-białego (0 lub 255).

**Zastosowanie:**
- Segmentacja obiektów
- Wykrywanie tekstu
- Analiza binarna

**Parametry:** Próg 127

**Wynik:** Piksele poniżej progu = czarne, powyżej = białe

---

### 8. ADAPTIVE - Progowanie adaptacyjne
**Co robi:** Progowanie z lokalnie dostosowanym progiem.

**Zastosowanie:**
- Segmentacja przy nierównym oświetleniu
- Wykrywanie tekstu w trudnych warunkach
- Lepsza jakość niż zwykłe progowanie

**Zaleta:** Działa dobrze przy zmiennym oświetleniu

---

### 9. SOBEL - Detekcja krawędzi Sobel
**Co robi:** Wykrywa krawędzie używając operatora Sobela (gradient).

**Zastosowanie:**
- Detekcja krawędzi poziomych i pionowych
- Analiza gradientu obrazu
- Wykrywanie zmian intensywności

**Wynik:** Obraz gradientu (jasne = silne krawędzie)

---

### 10. LAPLACIAN - Detekcja krawędzi Laplacian
**Co robi:** Wykrywa krawędzie używając operatora Laplace'a.

**Zastosowanie:**
- Detekcja krawędzi we wszystkich kierunkach
- Wykrywanie ostrości obrazu
- Analiza drugiej pochodnej

**Wynik:** Podkreślone krawędzie

---

### 11. CONTOURS - Detekcja konturów
**Co robi:** Znajduje i rysuje kontury obiektów na obrazie.

**Zastosowanie:**
- Wykrywanie kształtów obiektów
- Liczenie obiektów
- Analiza geometrii

**Wynik:** Zielone kontury narysowane na oryginalnym obrazie

---

### 12. FACE_DETECTION - Detekcja twarzy
**Co robi:** Wykrywa twarze używając klasyfikatora Haar Cascade.

**Zastosowanie:**
- Wykrywanie twarzy na zdjęciach
- Rozpoznawanie ludzi
- Analiza portretów

**Wynik:** Zielone prostokąty wokół wykrytych twarzy z etykietą "Face"

**Uwaga:** Działa najlepiej z twarzami en face (z przodu)

---

### 13. SHARPEN - Wyostrzenie
**Co robi:** Wyostrza obraz podkreślając szczegóły.

**Zastosowanie:**
- Poprawa ostrości rozmytych zdjęć
- Podkreślenie detali
- Poprawa jakości obrazu

**Efekt:** Obraz staje się bardziej wyrazisty

---

### 14. EMBOSS - Efekt wytłoczenia
**Co robi:** Tworzy efekt 3D wytłoczenia/rzeźby.

**Zastosowanie:**
- Efekty artystyczne
- Podkreślenie struktury
- Wizualizacja głębi

**Wynik:** Obraz wygląda jak wytłoczony w metalu

---

## Detekcja obiektów YOLO

### 15. YOLO_DETECT - Detekcja obiektów (szybka)
**Model:** YOLOv8n (nano)

**Co robi:** Wykrywa i klasyfikuje 80 klas obiektów (ludzie, zwierzęta, pojazdy, przedmioty).

**Zastosowanie:**
- Szybka detekcja obiektów w czasie rzeczywistym
- Analiza zawartości obrazu
- Liczenie obiektów

**Wynik:**
- Kolorowe prostokąty wokół obiektów
- Etykiety z nazwą klasy i pewnością (np. "person: 0.95")
- Lista wykrytych obiektów w konsoli

**Czas:** ~50-100ms

**Wykrywane klasy:** person, car, dog, cat, bicycle, motorcycle, airplane, bus, train, truck, boat, chair, table, laptop, phone, book, bottle, cup, fork, knife, spoon, bowl, banana, apple, sandwich, orange, pizza, donut, cake i wiele innych (80 klas COCO)

---

### 16. YOLO_DETECT_MEDIUM - Detekcja obiektów (średnia)
**Model:** YOLOv8s (small)

**Co robi:** Dokładniejsza detekcja obiektów niż wersja szybka.

**Zastosowanie:**
- Balans między szybkością a dokładnością
- Detekcja mniejszych obiektów
- Lepsza klasyfikacja

**Czas:** ~100-200ms

**Zaleta:** Wykrywa więcej obiektów i z większą pewnością

---

### 17. YOLO_DETECT_LARGE - Detekcja obiektów (dokładna)
**Model:** YOLOv8m (medium)

**Co robi:** Najdokładniejsza detekcja obiektów.

**Zastosowanie:**
- Profesjonalna analiza obrazu
- Wykrywanie małych i trudnych obiektów
- Maksymalna dokładność

**Czas:** ~200-400ms

**Zaleta:** Najwyższa dokładność i najmniej fałszywych detekcji

---

### 18. YOLO_SEGMENT - Segmentacja obiektów
**Model:** YOLOv8n-seg

**Co robi:** Wykrywa obiekty i tworzy precyzyjne maski segmentacji.

**Zastosowanie:**
- Precyzyjna segmentacja obiektów
- Wydzielanie tła
- Analiza kształtów

**Wynik:**
- Kolorowe, półprzezroczyste maski na obiektach
- Kontury obiektów
- Etykiety z nazwą i pewnością

**Czas:** ~100-200ms

**Zaleta:** Dokładne wyznaczenie granic obiektów (nie tylko prostokąty)

---

## Skróty klawiszowe

### W konsoli:
- **0** - Wyjście z programu
- **1-18** - Wybór transformacji
- **C** - Zmiana obrazu
- **ENTER** - Potwierdzenie/powrót do menu
- **Ctrl+C** - Awaryjne przerwanie programu

### W oknie obrazu:
- **Dowolny klawisz** - Zamknięcie okna i powrót do menu
- **ESC** - Zamknięcie okna

---

## Rozwiązywanie problemów

### Problem: "YOLO nie jest dostępne"
**Rozwiązanie:**
```bash
pip install ultralytics
```

### Problem: Okno obrazu nie pojawia się
**Rozwiązanie:**
1. Sprawdź czy obraz został poprawnie wczytany
2. Upewnij się, że ścieżka do obrazu jest prawidłowa
3. Spróbuj innego obrazu

### Problem: Detekcja twarzy nie działa
**Rozwiązanie:**
- Upewnij się, że twarze są widoczne z przodu
- Użyj obrazu o dobrej jakości
- Twarze powinny być wyraźne i dobrze oświetlone

### Problem: YOLO nie wykrywa obiektów
**Rozwiązanie:**
1. Spróbuj użyć YOLO_DETECT_LARGE (opcja 17) dla lepszej dokładności
2. Upewnij się, że obiekty należą do 80 klas COCO
3. Sprawdź jakość i rozdzielczość obrazu

### Problem: Program działa wolno
**Rozwiązanie:**
1. Użyj YOLO_DETECT (opcja 15) zamiast LARGE
2. Zmniejsz rozmiar obrazu
3. Użyj prostszych transformacji (1-14)

### Problem: Błąd przy pobieraniu obrazu z URL
**Rozwiązanie:**
1. Sprawdź połączenie internetowe
2. Upewnij się, że URL prowadzi bezpośrednio do pliku obrazu
3. Spróbuj innego URL

---

## Przykładowe scenariusze użycia

### Scenariusz 1: Analiza zdjęcia z wakacji
1. Wybierz opcję **1** (plik z dysku)
2. Wybierz zdjęcie z wakacji
3. Użyj **YOLO_DETECT** (opcja 15) aby zobaczyć co jest na zdjęciu
4. Użyj **FACE_DETECTION** (opcja 12) aby wykryć twarze

### Scenariusz 2: Poprawa jakości starego zdjęcia
1. Wczytaj stare, rozmyte zdjęcie
2. Użyj **SHARPEN** (opcja 13) aby wyostrzyć
3. Porównaj z oryginałem

### Scenariusz 3: Analiza obrazu z internetu
1. Wybierz opcję **2** (URL)
2. Wklej link do obrazu (np. z Unsplash)
3. Użyj **YOLO_SEGMENT** (opcja 18) aby zobaczyć segmentację

### Scenariusz 4: Detekcja krawędzi
1. Wczytaj dowolny obraz
2. Użyj **CANNY** (opcja 5) dla podstawowej detekcji
3. Porównaj z **EDGE_DETECTION** (opcja 6)
4. Porównaj z **SOBEL** (opcja 9)

---

## Wskazówki

✅ **Najlepsze praktyki:**
- Używaj obrazów o dobrej jakości (min. 640x480)
- Dla detekcji YOLO używaj obrazów z wyraźnymi obiektami
- Eksperymentuj z różnymi transformacjami na tym samym obrazie
- Zapisuj ciekawe wyniki (zrzut ekranu)

⚠️ **Uwagi:**
- Pierwsze uruchomienie YOLO pobierze modele (~6-50 MB)
- YOLO działa najlepiej na obrazach z dobrym oświetleniem
- Niektóre transformacje wymagają obrazu w skali szarości (automatyczna konwersja)

📝 **Zalecane formaty obrazów:**
- JPG/JPEG - najczęstszy, dobra kompresja
- PNG - bez strat, przezroczystość
- BMP - bez kompresji, duże pliki

---

## Kontakt i wsparcie

W razie problemów sprawdź:
- `README_YOLO.md` - szczegółowe informacje o YOLO
- `requirements.txt` - lista wymaganych bibliotek

---

**Wersja:** 1.0  
**Data:** 2025-11-04  
**Autor:** Program transformacji i detekcji obrazów
