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)

Obtain the plugin distribution package (ZIP archive containing the amcr_viewer directory).
Launch QGIS.
Navigate to Plugins → Manage and Install Plugins...
Select the Install from ZIP tab.
Locate the source ZIP file and click Install Plugin.
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 (only in Czech).

3.3 Layer Structure & Attributes

Upon successful retrieval, the plugin generates up to three temporary memory layers:

AMCR_[Akce|Lokalita]_Polygony
AMCR_[Akce|Lokalita]_Linie
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]

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]

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:

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.
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.
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.
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 (only in Czech).
AMCR Viewer tutorial (only in Czech).
Import/Export. Pluginy propojující QGIS s AMČR [poster] (only in Czech; valid for v1.3.2).

README.md Unescape Escape

AMCR Viewer: QGIS Plugin Documentation

1. Overview