# Schemat i Opis Działania Wtyczki Power EZiUDP

**Power EZiUDP** to wtyczka dla programu QGIS, która umożliwia szybkie i proste wyszukiwanie oraz podłączanie usług sieciowych WMS i WFS pochodzących z oficjalnej ewidencji zbiorów i usług danych przestrzennych (EZiUDP) prowadzonej przez Główny Urząd Geodezji i Kartografii (GUGiK). Wtyczka ułatwia pracę z polskimi rejestrami publicznymi bezpośrednio z poziomu interfejsu QGIS.

---

## 📂 Struktura Plików i Architektura

Wtyczka składa się z następujących kluczowych elementów:

| Plik / Folder | Typ | Opis |
| :--- | :--- | :--- |
| `__init__.py` | Plik Python | Inicjalizuje wtyczkę w środowisku QGIS, definiując funkcję `classFactory` zwracającą instancję głównej klasy wtyczki. |
| `Power_EZiUDP.py` | Plik Python | Główny plik z logiką biznesową wtyczki. Odpowiada za wyszukiwanie online/offline, integrację z mapą QGIS, zarządzanie warstwami TERYT i odpytywanie serwerów WMS/WFS. |
| `Power_EZiUDP_dockwidget.py` | Plik Python | Klasa panelu bocznego (dock widget). Odpowiada za dynamiczną stylizację (QSS), obsługę cieni i interakcję z widżetami interfejsu. |
| `Power_EZiUDP_dockwidget_base.ui` | Plik Qt Designer | Definicja interfejsu użytkownika w formacie XML utworzona w programie Qt Designer. |
| `style.qss` | Plik Stylu | Arkusz stylów Qt (QSS) definiujący spójny i nowoczesny wygląd panelu dostosowany do ciemnego i jasnego motywu QGIS. |
| `backup.sqlite` | Baza Danych | Lokalna baza danych SQLite przechowująca kopię zapasową ewidencji EZiUDP do działania w trybie offline. |
| `metadata.txt` | Plik Tekstowy | Metadane wtyczki (wersja, autor, opis, minimalna wersja QGIS) wymagane przez oficjalne repozytorium wtyczek. |
| `powiaty.geojson`<br>`gminy.geojson`<br>`wojewodztwa.geojson` | Pliki Przestrzenne | Zakresy geometryczne jednostek podziału terytorialnego Polski, używane przy określaniu kodu TERYT na podstawie kliknięcia na mapie. |
| `resources.qrc` / `resources.py` | Pliki Qt | Zasoby graficzne wtyczki (ikony). |

---

## 🛠️ Kluczowe Funkcjonalności

### 1. Wyszukiwanie Zbiorów i Usług (Online i Offline)
Wtyczka odpytuje wyszukiwarkę EZiUDP GUGiK. Użytkownik może szukać usług według:
*   **Jednostki administracyjnej**: Województwo, Powiat, Gmina lub Jednostki centralne.
*   **Kodu TERYT lub Nazwy**: Pole TERYT posiada autouzupełnianie (`QCompleter`) na podstawie załadowanych danych GeoJSON.
*   **Dodatkowych filtrów**: Nazwa instytucji (organu), fraza w nazwie zbioru, adres.
*   **Trybu Offline**: W przypadku braku połączenia internetowego lub zaznaczenia opcji "Wymuś offline", wyszukiwanie odbywa się w lokalnej bazie `backup.sqlite`.

### 2. Określanie TERYT na Podstawie Lokalizacji (Point Tool)
Narzędzie wskazania na mapie (`PointTool`) pozwala użytkownikowi kliknąć w dowolne miejsce na mapie QGIS:
1.  Współrzędne kliknięcia są transformowane do układu warstwy TERYT.
2.  Wtyczka wyszukuje przecięcia z załadowanym plikiem GeoJSON (`wojewodztwa`, `powiaty` lub `gminy`).
3.  Zasięg znalezionej jednostki jest podświetlany na mapie za pomocą półprzezroczystego wieloboku (`QgsRubberBand`).
4.  W przypadku trafienia na kilka jednostek (np. nakładające się granice), otwiera się okno wyboru `TerytSelectionDialog`, które umożliwia podgląd i precyzyjny wybór jednostki, po czym kod TERYT jest automatycznie wpisywany do panelu wyszukiwania.

### 3. Zaawansowane Podłączanie Usług (Layer Selection Manager)
Po kliknięciu "Dodaj" przy usłudze WMS/WFS:
1.  Wtyczka pobiera dokument `GetCapabilities` usługi.
2.  Analizuje dostępne warstwy (nazwy i tytuły) za pomocą wyrażeń regularnych.
3.  Otwiera okno `LayerSelectionDialog`, gdzie użytkownik może filtrować, zaznaczać pojedyncze lub wszystkie warstwy, kopiować ich nazwy do schowka, a dla usług WFS opcjonalnie ograniczyć pobieranie danych tylko do bieżącego widoku mapy (`restrictToRequestBBOX`).

### 4. Walidacja Usług (GUGiK Validator)
Integracja z oficjalnym Walidatorem Usług GUGiK:
*   **Walidacja standardowa**: Przekierowuje do walidatora online z parametrami usługi.
*   **Walidacja ze współrzędnymi**: Dla specyficznych baz (np. GESUT, BDOT500, BDSOG, RCN) wtyczka pozwala na wskazanie konkretnego obiektu na mapie, pobiera jego współrzędne w układzie EPSG:2180, i przesyła je do walidatora w celu szczegółowej analizy poprawności odpowiedzi serwisu.

### 5. Aktualizacja Bazy Offline
Przycisk "Aktualizuj" wysyła zapytanie pobierające całą bazę EZiUDP (`showall`). Dane są parsowane i zapisywane do pliku `backup.sqlite`. Zapewnia to pełną autonomię wtyczki podczas pracy w terenie bez dostępu do sieci.

---

## 📊 Schemat Działania Wtyczki (Diagram Przepływu)

Poniższy diagram przedstawia przepływ danych i logikę działania wtyczki od interakcji użytkownika do dodania warstwy na mapę.

```mermaid
graph TD
    %% Definicja Stylów
    classDef user fill:#e1f5fe,stroke:#039be5,stroke-width:2px;
    classDef process fill:#f3e5f5,stroke:#8e24aa,stroke-width:2px;
    classDef db fill:#efebe9,stroke:#5d4037,stroke-width:2px;
    classDef decision fill:#fff9c4,stroke:#fbc02d,stroke-width:2px;

    %% Interakcja użytkownika
    Start([Uruchomienie wtyczki]) --> InitDb[Inicjalizacja DB sqlite i Completera]
    InitDb --> UI[Wyświetlenie DockWidget]

    %% 1. Metoda wskazania na mapie
    UI -->|Kliknięcie wskaźnika mapy| PointTool[Aktywacja PointTool]
    PointTool -->|Kliknięcie na mapie| GetCoords[Pobranie współrzędnych i transformacja CRS]
    GetCoords --> QueryGeoJSON[Przeszukanie GeoJSON: powiaty/gminy/wojewodztwa]
    QueryGeoJSON --> CheckUnits{Ile jednostek znaleziono?}:::decision
    CheckUnits -->|0| MsgNoUnit[Komunikat: Nie znaleziono jednostki]
    CheckUnits -->|1| SetTeryt[Wpisanie kodu TERYT do pola]:::process
    CheckUnits -->|>1| TerytDlg[Okienko wyboru TerytSelectionDialog + RubberBand]:::process
    TerytDlg -->|Wybór użytkownika| SetTeryt

    %% 2. Proces wyszukiwania
    SetTeryt --> Search[Kliknięcie Wyszukaj]:::user
    UI -->|Ręczne wpisanie parametrów| Search
    Search --> CheckOffline{Czy włączony wymuszony tryb offline?}:::decision
    
    CheckOffline -->|Tak| DBRead[(Odczyt z backup.sqlite)]:::db
    CheckOffline -->|Nie| OnlineRequest[Zapytanie HTTP do integracja.gugik.gov.pl]:::process
    
    OnlineRequest -->|Błąd połączenia| FallbackOffline[Komunikat: Szukam w bazie offline...]:::process
    FallbackOffline --> DBRead
    OnlineRequest -->|Sukces| ParseHTML[Parsowanie odpowiedzi HTML wyrażeniami regularnymi]:::process
    
    ParseHTML --> RenderTable[Wypełnienie Tabeli Wyników]:::process
    DBRead --> RenderTable

    %% 3. Akcje na wynikach
    RenderTable -->|Kliknięcie TERYT| ZoomTo[Przybliżenie mapy do zakresu jednostki administracyjnej]:::process
    RenderTable -->|Kliknięcie Preview 🌐| OpenGeoportal[Otwarcie Geoportalu z bbox i podłączonym WMS]:::process
    RenderTable -->|Kliknięcie Szczegóły 📃| OpenDetails[Menu: Szczegóły EZiUDP / Google / Zbiory organu]:::process
    RenderTable -->|Kliknięcie Dodaj WMS/WFS| GetCapabilities[Pobranie dokumentu GetCapabilities usługi]:::process
    
    GetCapabilities --> ParseLayers[Parsowanie warstw za pomocą Regex]:::process
    ParseLayers --> LayerDlg[Wyświetlenie LayerSelectionDialog z filtrowaniem]:::process
    LayerDlg -->|Zaznaczenie warstw i akceptacja| AddToMap[Dodanie warstwy raster/vector do projektu QGIS]:::process
    AddToMap --> End([Koniec - Warstwa na mapie])

    %% Przypisanie klas stylów
    class UI,Search,PointTool user;
    class InitDb,GetCoords,QueryGeoJSON,SetTeryt,TerytDlg,OnlineRequest,ParseHTML,RenderTable,ZoomTo,OpenGeoportal,OpenDetails,GetCapabilities,ParseLayers,LayerDlg,AddToMap process;
    class DBRead db;
```

---

## 🛠️ Używane Moduły i Klasy QGIS

Wtyczka łączy standardowe biblioteki Pythona z silnikiem QGIS API:
*   **Interfejs użytkownika**: `QtWidgets`, `PyQt.QtCore`, `uic` (ładowanie `.ui` w locie), dynamiczna podmiana stylów za pomocą arkusza QSS (`style.qss`).
*   **Operacje sieciowe**: `requests` (pobieranie GetCapabilities, eziudp online), `webbrowser`, `QDesktopServices` (otwieranie stron zewnętrznych i walidatora).
*   **Baza danych**: `sqlite3` (przechowywanie i przeszukiwanie zduplikowanych rekordów, indeksowanie unikalne na nazwie, terycie i urlach).
*   **QGIS Core API**:
    *   `QgsVectorLayer` & `QgsRasterLayer`: Reprezentacja i dodawanie usług do mapy.
    *   `QgsProject`: Zarządzanie warstwami w projekcie.
    *   `QgsRubberBand`: Dynamiczne podświetlanie geometrii TERYT na płótnie mapy.
    *   `QgsCoordinateTransform` & `QgsCoordinateReferenceSystem`: Transformacja współrzędnych w locie pomiędzy CRS mapy a CRS warstwy GeoJSON (np. EPSG:2180).
    *   `QgsMapToolEmitPoint`: Obsługa kliknięć użytkownika na płótnie mapy.
