mirror of
https://github.com/ARUP-CAS/aiscr-qgis-amcr-viewer.git
synced 2026-06-17 11:22:53 +02:00
Claude
64ec1ea7fd
- metadata.txt: icon ukazoval na neexistující download.png – plugin se ve správci zásuvných modulů zobrazoval bez ikony; nastaveno na akce.png. - Workflow: actions/checkout v2→v4 (v2 je deprecated, Node 12) a softprops/action-gh-release v1→v2. - README: poznámka, že knihovna requests nemusí být na Linuxu součástí systémové instalace QGIS.
183 lines
9.9 KiB
Markdown
183 lines
9.9 KiB
Markdown
# AMCR Viewer: QGIS Plugin Documentation
|
||
|
||
[](https://www.gnu.org/licenses/gpl-3.0)
|
||
|
||
**Platform:** QGIS 3.44.0–4.99.0
|
||
|
||
**Module Type:** Data Acquisition & Visualization
|
||
|
||
**Source Data:** Archaeological Map of the Czech Republic (AIS CR)
|
||
|
||
---
|
||
|
||
## 1. Overview
|
||
|
||
**AMCR Viewer** is a QGIS plugin designed to facilitate direct access to the Digital Archive of the Archaeological Map of the Czech Republic (AMČR). It allows researchers to **query, retrieve, and visualize *Fieldwork events* and *Sites* data (metadata and geometry) directly within the GIS environment**, eliminating the need to manually export data from the web interface. Both *Fieldwork events* and *Sites* layers may optionally include component-level data (period and activity area) embedded directly in the attribute table. The plugin supports both **anonymous (public) access** and **authenticated access** for users with an AMČR account.
|
||
|
||
### Key Features
|
||
|
||
* **Spatial Querying:** Option to filter records based on the current map canvas extent (Bounding Box).
|
||
* **Advanced Attribute Filtering:** Supports multi-criteria filtering using controlled vocabularies.
|
||
* **Dynamic Geometry Retrieval:** Automatically downloads and categorizes spatial data into Point, Line, and Polygon layers.
|
||
* **Semantic Interoperability:** Automatically translates internal system codes into human-readable labels using the AIS CR API.
|
||
* **Authenticated Access:** Users with an AMČR account can log in to access non-public records.
|
||
|
||
## 2. Installation Guide
|
||
|
||
**Install the latest version of the plugin from the QGIS plugin repository.**
|
||
|
||
**OR** (*in case you need older version*)
|
||
|
||
1. *Obtain the [plugin distribution package](https://github.com/ARUP-CAS/aiscr-qgis-amcr-viewer/releases) (ZIP archive containing the `amcr_viewer` directory).*
|
||
2. *Launch QGIS.*
|
||
3. *Navigate to Plugins → Manage and Install Plugins...*
|
||
4. *Select the Install from ZIP tab.*
|
||
5. *Locate the source ZIP file and click Install Plugin.*
|
||
6. *Upon successful installation, the AMCR Viewer button will appear in the toolbar.*
|
||
|
||
## 3. User Manual
|
||
|
||
### 3.1 Authentication (Optional)
|
||
|
||
By default, the plugin accesses only publicly available records (accessibility = anonymous). To access non-public data, log in using your AMČR account:
|
||
|
||
* Click the dropdown arrow on the AMCR Viewer toolbar button and select **Přihlásit se**.
|
||
* Enter your e-mail and password. Credentials are encrypted and stored securely in the **QGIS Authentication Manager** (DPAPI on Windows, Keychain on macOS, encrypted SQLite on Linux).
|
||
* Stored credentials are reused automatically across sessions. To update or remove them, open the login dialog again.
|
||
|
||
### 3.2 Data Retrieval
|
||
|
||
To initiate a search query, click either the **Stáhnout data akcí** or the **Stáhnout data lokalit** option from the dropdown menu. The filter dialog provides the following options. Shown options vary based on the chosen tool.
|
||
|
||
* **Spatial Filter:** *Checkbox "Omezit vyhledávání rozsahem okna":* If checked, the query is restricted to the geographical area currently visible in the QGIS canvas. If unchecked, the query searches the entire database (use with caution regarding data volume).
|
||
* **Positive findings only:** If checked, only *PIANs* belonging to Documentation units marked as "Type of evidence" = "positive" are included. *(Fieldwork events only.)*
|
||
|
||
* **Attribute Filters:**
|
||
* The dialog uses "Picker" widgets for controlled vocabularies (common: Region, District, Cadastral area, Period, Activity Area, *PIAN* accuracy, Accessibility; *events* related: Organisation, Researcher, Event type; *sites* related: Site type and class, Level of confidence, State of preservation).
|
||
* Click **Vybrat...** to open a searchable selection window. Multiple values can be selected simultaneously (Logic: OR).
|
||
|
||
* **Codelists (Hesláře):**
|
||
* Controlled vocabularies are downloaded from the AMČR OAI-PMH API and cached locally in `codelists/heslar.csv`.
|
||
* To refresh all codelists, click the **Aktualizovat hesláře 🔄** button in the filter dialog. This runs as a background task and may take a few minutes.
|
||
|
||
* **Components:** Check **Načíst komponenty** to include period and activity area data directly in the output layers.
|
||
> ⚠ When components are loaded, spatial features are duplicated — each feature corresponds to one component. Spatial analyses (areas, counts) may be inaccurate.
|
||
|
||
* If no filter is used, all accessible Fieldwork events/PIANs are returned (the number of records is capped at 20 000; it is advisable to set at least one filter).
|
||
|
||
For a more in-depth tutorial refer to the [AMČR Documentation](https://amcr-help.aiscr.cz/digiarchiv/qgis-viewer.html) (only in Czech).
|
||
|
||
### 3.3 Layer Structure & Attributes
|
||
|
||
Upon successful retrieval, the plugin generates up to three temporary memory layers:
|
||
|
||
1. **AMCR\_[Akce|Lokalita]\_Polygony**
|
||
2. **AMCR\_[Akce|Lokalita]\_Linie**
|
||
3. **AMCR\_[Akce|Lokalita]\_Body**
|
||
|
||
Layers are only created if the query returns features of the corresponding geometry type. All layers share the same attribute schema.
|
||
|
||
#### 3.3.1 Common fields
|
||
|
||
| Field | Description |
|
||
| --- | --- |
|
||
| pian | PIAN (spatial identifier) ID |
|
||
| presnost | Spatial deviation \[units/tens/hundreds of meters/defined by cadastre\] |
|
||
| pian\_typ | \[point/line/polygon\] |
|
||
| dj | Documentation unit ID |
|
||
| typ\_dj | \[trench/event part/whole event/cadastral territory\] |
|
||
| definicni\_body | Feature centroid in WGS-84 coordinate system |
|
||
| akce / lokalita | Fieldwork event / Site ID |
|
||
| odkaz\_do\_digiarchivu | Link to the record in the Digital Archive |
|
||
| okres | District |
|
||
| katastr | Main cadastral area |
|
||
| dalsi\_katastry | Other cadastral areas, if the event extends beyond the main cadastre |
|
||
| Přístupnost | Record accessibility \[A/B/C/D\] |
|
||
|
||
#### 3.3.2 Fields related to *Fieldwork events*
|
||
|
||
| Field | Description |
|
||
| --- | --- |
|
||
| akce\_lokalizace | Verbal description of the event location |
|
||
| vedouci | Main fieldwork manager |
|
||
| organizace | Organisation conducting the research |
|
||
| specifikace\_data | \[exact date/exact years/sometime in years\] |
|
||
| zahajeni | Event start date |
|
||
| ukonceni | Event end date |
|
||
| hlavni\_typ | Primary research method |
|
||
| vedlejsi\_typ | Secondary research method |
|
||
| zjisteni | Did the research reveal archaeological contexts? \[positive/negative\] |
|
||
| nahrazuje\_NZ | Replaces a fieldwork report? \[yes/no\] |
|
||
|
||
#### 3.3.3 Fields related to *Sites*
|
||
|
||
| Field | Description |
|
||
| --- | --- |
|
||
| nazev\_lokality | Site name |
|
||
| popis\_lokality | Site description |
|
||
| typ\_lokality | Site classification by definition method |
|
||
| druh\_lokality | Site classification by the nature of identified field relics |
|
||
| zachovalost | Site preservation state |
|
||
|
||
#### 3.3.4 Component fields (only when *Načíst komponenty* is checked)
|
||
|
||
| Field | Description |
|
||
| --- | --- |
|
||
| komponenta | Component ID |
|
||
| komponenta\_areal | Activity area \[settlement/burial area/field/…\] |
|
||
| komponenta\_obdobi | Period \[Neolithic/High Middle Ages–Modern Period/…\] |
|
||
|
||
## 4. Technical Architecture
|
||
|
||
The plugin is developed in **Python 3** using the **PyQt6** framework for the GUI and the **Requests** library for HTTP communication.
|
||
|
||
> **Note:** The `requests` library is bundled with the QGIS installers for Windows and macOS. On Linux (distribution packages), it may need to be installed separately (e.g. `python3-requests`).
|
||
|
||
### 4.1 File Structure
|
||
|
||
* `amcr_viewer.py`: Entry point; handles GUI integration, toolbar/menu setup, and login flow.
|
||
* `amcr_dialog.py`: Manages the UI logic, including `AmcrFilterDialog`, `FilterableSelectionDialog`, and `LoginDialog`.
|
||
* `amcr_tools.py`: Core logic module. Handles authentication, API requests, pagination, data parsing, and vector layer generation.
|
||
* `amcr_codelists.py`: Manages local caching of controlled vocabularies (`codelists/heslar.csv`) downloaded via OAI-PMH.
|
||
|
||
### 4.2 Data Flow & API Integration
|
||
|
||
The plugin interacts with the following endpoints:
|
||
|
||
1. **Login API:**
|
||
* Endpoint: `https://digiarchiv.aiscr.cz/api/user/login`
|
||
* Method: `POST`
|
||
* Returns a session cookie used for subsequent authenticated requests.
|
||
* Credentials are stored in the QGIS Authentication Manager; the session is restored automatically if it expires mid-download.
|
||
|
||
2. **Search API (Solr):**
|
||
* Endpoint: `https://digiarchiv.aiscr.cz/api/search/query`
|
||
* Method: `GET`
|
||
* Parameters: `entity=akce|lokalita|pian`, `rows/page` (pagination), `mapa=true`.
|
||
* Logic: Paginated in batches of 500 records (metadata) and 200 records (geometries). A safety cap of 20 000 records is enforced.
|
||
|
||
3. **Translation API:**
|
||
* Endpoint: `https://digiarchiv.aiscr.cz/api/assets/i18n/cs.json`
|
||
* Function: Retrieves the mapping between system codes (e.g. `HES-xxxx`) and Czech labels. Cached in memory for the session.
|
||
|
||
4. **Codelists API (OAI-PMH):**
|
||
* Endpoint: `https://api.aiscr.cz/2.2/oai`
|
||
* Used for downloading controlled vocabularies (periods, regions, organisations, etc.) on demand.
|
||
|
||
### 4.3 Data Persistence
|
||
|
||
* **Vocabularies:** Stored in `codelists/heslar.csv`; updated on user request via the background task.
|
||
* **Layers:** Output layers are created as `memory` layers. They are non-persistent and will be lost if QGIS is closed without saving.
|
||
|
||
### 4.4 Constraints
|
||
|
||
* **Record Limit:** A safety cap of 20 000 records is enforced.
|
||
* **Batch Processing:** Geometry fetching is batched (200 IDs per request) to comply with URL length limitations and server load balancing.
|
||
* **Component duplication:** When components are loaded, each output feature corresponds to one component rather than one documentation unit. A single PIAN may therefore appear multiple times in the layer.
|
||
|
||
## 5. Links and resources
|
||
|
||
* [AMCR/Digiarchive Documentation](https://amcr-help.aiscr.cz/) (only in Czech).
|
||
* [AMCR Viewer tutorial](https://amcr-help.aiscr.cz/digiarchiv/qgis-viewer.html) (only in Czech).
|
||
* [Import/Export. Pluginy propojující QGIS s AMČR \[poster\]](https://zenodo.org/records/20504909) (only in Czech; valid for v1.3.2).
|