How kojix2/gpscan_viewer works
1. What this repo is
- gpscan_viewer is a small Qt 6 desktop application for viewing GrandPerspective-compatible scan XML files, including XML emitted by gpscan.
- Architecturally, it is a single native GUI app with a narrow pipeline: XML input → in-memory tree model → layout computation → custom canvas rendering.
2. Top-level runtime boundary
- The executable entry point is src/main.cpp.
- From there, the app boots a Qt application and creates the main window/UI shell defined in ViewerWindow.*.
- There is no backend service or network layer; all data is local file input and in-process rendering.
3. Input and parsing subsystem
- src/TreeReader.* is the ingestion layer for the scan XML format.
- It is responsible for turning on-disk XML into the internal tree structure consumed by the rest of the app.
- resources/sample.xml serves as a bundled example input and is useful for understanding expected file shape.
4. Core data model
- src/TreeModel.* holds the logical representation of the scan tree.
- This is the central domain object that bridges parsing, layout, and rendering.
- The model likely stores hierarchy, sizes/weights, and metadata needed to draw treemap-style boxes.
5. Layout / geometry subsystem
- src/TreeLayout.* computes the 2D arrangement of the tree nodes for display.
- This layer transforms the logical hierarchy into screen-space rectangles or regions.
- It is the key boundary between “data” and “visualization,” and probably encapsulates treemap layout rules.
6. Rendering subsystem
- src/CanvasWidget.* is the custom Qt widget that performs drawing.
- It consumes the layout/model output and paints the visualization in the main window.
- This widget is the main interactive surface of the application and the likely place for zoom/selection handling if present.
7. Visual styling and color mapping
- src/Palette.* centralizes color selection for the visualization.
- This is a separate concern from layout so the app can vary appearance without changing geometry.
- It likely maps node attributes or categories to colors used by the canvas renderer.
8. UI composition
- src/ViewerWindow.* is the application shell that connects parsing, model state, and the canvas.
- It is the main coordination layer for user actions such as opening a file and refreshing the view.
- The window likely owns or references the central model and the canvas widget.
9. Shared utilities
- src/Utils.* contains cross-cutting helper functions used across parsing, layout, or rendering.
- Keeping these helpers separate prevents the domain modules from accumulating incidental logic.
10. Data flow through the app
- The primary flow is: XML file → TreeReader → TreeModel → TreeLayout → CanvasWidget → on-screen visualization.
- Palette influences the final visual output during rendering, but does not alter the underlying data model.
- ViewerWindow coordinates the handoff between these stages.
11. Build and packaging boundary
- The project is built with CMake (CMakeLists.txt) and depends on Qt 6 and zlib as noted in the README.
- The build also supports packaging via CPack for DEB/RPM outputs.
- This matters architecturally because the repo is designed as a native distributable GUI tool, not a library or service.
12. Testing and automation
- tests/TestMain.cpp indicates a dedicated test entry point, suggesting a Qt/CMake test target rather than end-to-end UI automation.
- GitHub Actions workflows in .github/workflows/ provide CI build validation and screenshot-related automation.
- That implies the repo values regression checking around both compilation and visual output.
13. Desktop integration
- resources/gpscan_viewer.desktop shows this app is intended to integrate with desktop environments on Linux.
- The resources/ directory also reinforces that the project is packaged as a desktop utility with sample assets rather than a service or library.
14. Overall architecture to diagram
- A good diagram would show four main zones: file input/parsing, domain model, layout/rendering, and Qt windowing/UI.
- The central flow is strictly one-way from parsed XML into visual state, with the main window orchestrating user interaction around that pipeline.
Main entry points: ViewerWindow.h Viewer Window · TreeReader.h Tree Reader · CanvasWidget.h Canvas Widget · TreeModel.h Tree Model
Components 13
Qt app
Desktop application runtime and UI shell
- Main · Qt application startup and window creation
src/main.cpp - Viewer Window · Main window that coordinates file loading and view updates
src/ViewerWindow.h
Scan pipeline
XML ingestion, model, layout, and rendering
- Tree Reader · Reads GrandPerspective-compatible scan XML into memory
src/TreeReader.h - Tree Model · In-memory hierarchy and node metadata used by the app
src/TreeModel.h - Tree Layout · Computes display rectangles for the tree visualization
src/TreeLayout.h - Canvas Widget · Paints the treemap and handles interactive view behavior
src/CanvasWidget.h - Palette · Centralized color selection for visual rendering
src/Palette.h - Utils · Shared helper routines used across the app
src/Utils.h - Sample XML · Bundled example scan file showing the expected input shape
resources/sample.xml
Build & CI
Build configuration, tests, and automation
- CMake · Project build and packaging configuration
CMakeLists.txt - Test Main · Dedicated test target entry point
tests/TestMain.cpp - CI Workflows · GitHub Actions builds and screenshot regression automation
.github/workflows/build.yml - Desktop File · Linux desktop integration metadata
resources/gpscan_viewer.desktop
Connections 15
- Main → Viewer Window: creates · Application startup instantiates the main window
- Viewer Window → Tree Reader: loads · Window triggers XML import for opened files
- Tree Reader → Tree Model: builds · Parsed XML becomes the in-memory tree model
- Tree Model → Tree Layout: feeds · Logical tree data is transformed into display geometry
- Tree Layout → Canvas Widget: renders · Computed rectangles are painted on the custom widget
- Tree Model → Canvas Widget: supplies · The canvas consumes model state for drawing and selection
- Palette → Canvas Widget: colors · Color mapping is applied during painting
- Viewer Window → Canvas Widget: hosts · Main window embeds the drawing surface
- Utils → Tree Reader: supports · Shared helpers assist parsing and data handling
- Utils → Tree Layout: supports · Shared helpers assist layout calculations
- CMake → Main: builds · CMake config defines the application target
- CMake → Test Main: builds · CMake config defines the test target
- CI Workflows → CMake: checks · Automation validates builds and visual regressions
- Desktop File → Viewer Window: integrates · Desktop entry exposes the app in native environments
- Sample XML → Tree Reader: exercises · Bundled sample demonstrates the input format