Architecture

Entry Points

The plugin entry point is the Roll class in roll.py. It integrates with QGIS, creates plugin actions, and launches the main application window.

The main UI lives in RollMainWindow in roll_main_window.py. It loads the Qt Designer UI, wires menu and toolbar actions, and coordinates project, plotting, property editing, and processing services.

Core Data Model

The survey model is centered on RollSurvey in roll_survey.py.

RollSurvey owns:

  • survey geometry such as blocks, templates, seeds, and patterns;

  • coordinate transforms and CRS handling;

  • binning-related state; and

  • rendering support for the plotting views.

Project files are stored as XML .roll documents. The XML keeps the survey hierarchy together with metadata such as the CRS WKT string.

Processing Model

Long-running geometry and binning work is pushed onto QThread workers. This keeps the GUI responsive while heavy processing runs in the background.

Numeric hot paths live in functions_numba.py with fallback behavior kept in mind for environments where Numba is unavailable.

Output and Analysis Storage

Analysis outputs are represented by RollOutput in roll_output.py. Full binning writes detailed per-trace information to memory-mapped analysis files so large datasets can be processed and inspected without forcing a full in-memory load.

UI Composition

The main window delegates substantial UI setup to focused modules such as the roll_main_window_create_* files. Additional controllers and services handle stateful concerns like:

  • property-panel behavior;

  • action enablement;

  • plotting navigation and redraw reuse;

  • project loading and saving; and

  • import and export workflows.

QGIS Integration

QGIS integration includes:

  • importing and exporting source and receiver geometry;

  • exporting rasters and outlines into the active QGIS project; and

  • supporting point-layer round-trips for editing outside Roll.

The plugin therefore sits between a compact internal survey definition and the more explicit geometry and raster products consumed in QGIS.

Documentation Boundary

The Sphinx documentation in help/source is intended to provide maintainable project documentation. The QGIS round-trip guide is maintained directly in the reStructuredText sources so it can be updated alongside the rest of the help.