Desktop GUI Tutorial

Note

The Desktop GUI module is under development. This tutorial will be updated with screenshots and detailed instructions in a future release.

This tutorial guides you through using PyArchInit-Mini’s desktop application for offline archaeological data management.

Overview

The desktop GUI provides a native application interface for PyArchInit-Mini, offering:

  • Offline Operation: Work without an internet connection

  • Native Performance: Faster response times compared to web interface

  • Desktop Integration: File system access, native dialogs, and OS integration

  • Cross-Platform: Available on Windows, macOS, and Linux

Prerequisites

  • PyArchInit-Mini installed with GUI dependencies

  • Python 3.9 or higher

  • Qt5 or Qt6 libraries (installed automatically)

Installation

Install PyArchInit-Mini with GUI support:

pip install pyarchinit-mini[gui]

Or if you already have PyArchInit-Mini installed:

pip install pyarchinit-mini[gui] --upgrade

Starting the Desktop Application

Launch the desktop GUI:

pyarchinit-mini-gui

Or from Python:

from pyarchinit_mini.gui import main
main()

The application window will open with the main interface.

Main Interface

The desktop application is organized into several main areas:

Top Menu Bar

  • File: New database, open database, save, export, quit

  • Edit: Undo, redo, preferences

  • View: Switch between modules, toggle sidebars

  • Data: Sites, US, inventory, documentation

  • Tools: Harris Matrix, reports, import/export

  • Help: Documentation, about, check for updates

Main Content Area

The central area displays the selected module’s content:

  • Data entry forms

  • Lists and tables

  • Visualization panels

  • Report previews

Status Bar

The bottom status bar shows:

  • Current database path

  • Record count

  • Active user

  • Connection status

Working with Sites

Creating a New Site

  1. Click Data → Sites or select Sites from the sidebar

  2. Click the New Site button in the toolbar

  3. Fill in the site information form:

    • Site name (required)

    • Location details

    • Site definition

    • Description

    • Coordinates (optional)

  4. Click Save to create the site

Editing Existing Sites

  1. Select a site from the sites list

  2. Click the Edit button or double-click the site

  3. Modify the site information

  4. Click Save to apply changes

Deleting Sites

  1. Select a site from the sites list

  2. Click the Delete button

  3. Confirm the deletion in the dialog

Warning

Deleting a site will also delete all associated stratigraphic units and finds. This action cannot be undone.

Managing Stratigraphic Units

Creating US Records

  1. Navigate to Data → US or select US from the sidebar

  2. Click New US in the toolbar

  3. Fill in the US form:

    • Select site (required)

    • Area and US number

    • Stratigraphic description

    • Interpretative description

    • Physical characteristics

    • Dating information

  4. Click Save to create the US record

Defining Relationships

  1. Open a US record

  2. Click the Relationships tab

  3. Add relationships:

    • Click Add Relationship

    • Select relationship type (covers, cuts, fills, etc.)

    • Select related US

    • Click Add

  4. The relationships will automatically update the Harris Matrix

Inventory Management

Recording Finds

  1. Go to Data → Inventory

  2. Click New Inventory Item

  3. Enter find details:

    • Inventory number

    • Find type and classification

    • Description

    • Provenance (site, area, US)

    • Conservation status

    • Measurements

    • Dating

  4. Click Save

Attaching Photos

  1. Open an inventory item

  2. Click the Media tab

  3. Click Add Photo

  4. Select image files from your computer

  5. Add captions and metadata

  6. Click Save

Harris Matrix Visualization

Generating the Matrix

  1. Navigate to Tools → Harris Matrix

  2. Select the site

  3. Click Generate Matrix

The application will:

  • Analyze all stratigraphic relationships

  • Calculate the correct layering sequence

  • Generate an interactive visualization

Interacting with the Matrix

  • Zoom: Use mouse wheel or pinch gesture

  • Pan: Click and drag

  • Select US: Click on a node to see details

  • Highlight Path: Right-click a node to trace relationships

Exporting the Matrix

  1. Click Export in the Matrix toolbar

  2. Choose format:

    • SVG (vector graphics)

    • PNG (raster image)

    • PDF (document)

    • GraphML (for analysis software)

  3. Select destination and click Save

Reports and Export

Generating Reports

  1. Go to Tools → Reports

  2. Select report type:

    • Site Report

    • US Summary

    • Inventory Catalog

    • Harris Matrix Document

  3. Configure report options

  4. Click Generate

  5. Preview the report

  6. Click Export to save as PDF

Exporting Data

Export your data for backup or analysis:

  1. Go to File → Export

  2. Select export format:

    • Excel (.xlsx)

    • CSV (comma-separated)

    • JSON (structured data)

    • SQL dump (full backup)

  3. Choose what to export:

    • All data

    • Selected site only

    • Custom selection

  4. Click Export and choose destination

Importing Data

Import data from external sources:

  1. Go to File → Import

  2. Select import format

  3. Choose file to import

  4. Map fields (if required)

  5. Review preview

  6. Click Import

Preferences and Settings

Access preferences: Edit → Preferences

General Settings

  • Default database location

  • Auto-save interval

  • Language selection

  • Date and number formats

Display Settings

  • Theme (light/dark)

  • Font size

  • Grid lines in tables

  • Icon size

Database Settings

  • Default database type (SQLite/PostgreSQL)

  • Connection timeout

  • Backup location

  • Auto-backup schedule

Keyboard Shortcuts

Common shortcuts:

  • Ctrl+N (Cmd+N on macOS): New record

  • Ctrl+S (Cmd+S): Save

  • Ctrl+F (Cmd+F): Find/Search

  • Ctrl+Z (Cmd+Z): Undo

  • Ctrl+Shift+Z (Cmd+Shift+Z): Redo

  • F5: Refresh data

  • Ctrl+Q (Cmd+Q): Quit application

Troubleshooting

Application Won’t Start

  • Verify GUI dependencies are installed: pip install pyarchinit-mini[gui]

  • Check Python version: python --version (must be 3.9+)

  • Try running with verbose output: pyarchinit-mini-gui --verbose

Database Connection Issues

  • Verify database path in Edit → Preferences → Database

  • Check file permissions for SQLite database files

  • For PostgreSQL, ensure server is running

Performance Issues

  • Close unused modules

  • Reduce auto-save frequency

  • Limit displayed records using filters

  • Check available disk space

Tips and Best Practices

Data Entry

  • Use keyboard shortcuts to speed up data entry

  • Configure auto-save to prevent data loss

  • Use templates for repetitive entries

  • Regularly backup your database

Organization

  • Use consistent naming conventions

  • Create a site-specific thesaurus

  • Document your workflow in site notes

  • Review and validate data regularly

Collaboration

  • Use version control for database files

  • Export regularly for team sharing

  • Document changes in commit messages

  • Use PostgreSQL for multi-user access

Next Steps

  • Explore the Web Interface Tutorial for remote access

  • Learn about Harris Matrix advanced features

  • Read the API Documentation for automation

  • Join the community forum for tips and support

See also

Getting Help