# afforix/therion architecture

> Architecture diagram of the GitHub repository afforix/therion, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/afforix/therion
- Repository: https://github.com/afforix/therion

## Overview

##### Project Type and Purpose
- Therion is a specialized cave surveying tool that takes survey data and produces complete, always up‐to‐date cave maps and realistic 3D models. It uses 2D maps as input and supports LRUD dimensions along with features like loop closure and blunder fixes.
- The README emphasizes its role in processing cave survey data into detailed maps and 3D models. This means that the software has several pipeline stages—from data input and parsing to geometric modeling and map rendering.

##### File Structure for Architectural Clues
- There are many directories and files focused on building, configuration, and compilation (e.g., CMakeLists.txt, Makefile, cmake/ scripts, toolchains). This indicates that the project is built in C/C++ with a robust build system.
- Several top-level directories hint at modular components:
- “loch”, “therion-main.cxx”, “therion.cxx”, and various “th***.cxx” files represent the core engine handling data input, processing, and output.
- “xtherion” directory contains Tcl scripts and files for the GUI/interactive or external control layer.
- “mpost” and “thbook” directories indicate post-processing, document generation (for book documentation), and map export functions.
- “extern” contains external libraries (Catch2 for testing, poly2tri, quickhull, shapelib) which are integrated for geometry processing and unit testing.
- “samples” provides example survey data and configuration files that likely demonstrate the usage and integration of the core engine.
- There are several test and utility files (utest-*.cxx, test_proj.sh) signifying an emphasis on verification and quality assurance.

##### Main Components
a. Core Engine & Processing Modules:
- Data Input & Parsing – Represented by sources such as thinput.cxx and thparse.cxx.
- Data Processing and Domain Logic – Modules handling geometry (e.g., thgeomag.cxx, tharea.cxx, thline.cxx), survey data (thsurvey.cxx, thdb2d*.cxx), and computation (thwarpp, thtf* modules).
- Error Handling & Logging – Modules like thlog.cxx, thexception.cxx.

b. Generation & Rendering:
- The transformation from raw 2D survey data to 3D models and maps seems to be handled in several sources (lxRender.cxx, lxGUI.cxx, and related “loch” components).
- Post-processing (in directories like mpost) for producing specific formats like PDF maps or other documented outputs.

c. User Interface and External Tools:
- The “xtherion” directory includes Tcl scripts for interactive use, which could serve as the frontend or a command interface for user commands.

d. External Dependencies:
- Geometry Processing Libraries (poly2tri, quickhull, shapelib) – which handle triangulation, convex hull calculations, etc.
- Test Framework – Catch2 in the extern directory.
- Build and Deployment Tools – CMake, Makefiles, and toolchain scripts which support multiple compilers and sanitize builds.

##### Detail the Relationships and Interactions
- Data flows from the input/parsing stage into the core processing engine where survey data is interpreted and transformed.
- After processing, the data is forwarded into the map generation modules that output 2D maps and 3D models.
- The user interface (through Tcl scripts in xtherion) interacts with the core engine to allow for real-time updates, manual adjustments (e.g., loop closure, blunder fixes), and visualization.
- External libraries provide support at specific stages – for example, computational geometry algorithms are invoked during model generation.
- The build system (CMake, Makefiles, and cmake scripts) orchestrates compiling all modules, linking against external libraries, and preparing deployment packages.

##### Architectural Patterns and Design Principles
- Modular Design: The separation of core processing, rendering, and interfacing functionalities is evident in the file structure.
- Extensibility: The existence of external libraries and numerous configuration and build scripts show that the system is designed to be extended and adapted (e.g., additional map export formats, test cases).
- Emphasis on Cross-Platform Build/Deployment: Toolchains and CMake scripts indicate support for different compilers and operating systems.

##### Specific Elements
- The “Map/Postprocessing Module” that converts processed data into rendered outputs (2D maps, 3D models, PDFs).
- Test modules or continuous integration (integrated with GitHub workflows, as seen in .github/workflows) – you may note these as a verification process feeding back into development.

##### Final Advice
- Maintain clarity: while it might be tempting to show every file, focus on grouping related functionality together (for example, all “th*.cxx” files can be grouped under the “Core Processing” module).

## Diagram (Mermaid)

```mermaid
flowchart TD
    BS("Build & Deployment System"):::build

    subgraph "Core Engine & Processing"
        CP1("Input & Parsing"):::core
        CP2("Data Processing"):::core
        CP1 --> CP2
    end

    subgraph "Map Generation & Rendering"
        LOCH("LOCH Module"):::map
        MPOST("Mpost"):::map
        LOCH --> MPOST
    end

    subgraph "User Interface & External Tools"
        XTH("xtherion Tools"):::ui
        LOCH_UI("LOCH GUI"):::ui
        XTH --> LOCH_UI
    end

    subgraph "External Dependencies"
        POLY("poly2tri"):::ext
        QH("quickhull"):::ext
        SH("shapelib"):::ext
        CATCH("catch2"):::ext
    end

    subgraph "Testing & Quality Assurance"
        TEST("Test Sources"):::test
        GITHUB("GitHub Workflows"):::test
    end

    BS --> CP1
    BS --> LOCH
    BS --> XTH

    CP2 --> LOCH
    XTH --> CP2
    CP2 --> XTH

    POLY --- CP2
    QH --- CP2
    SH --- CP2
    CATCH --- CP2

    POLY --- LOCH
    QH --- LOCH
    SH --- LOCH
    CATCH --- LOCH

    TEST --> BS
    GITHUB --> BS

    classDef build fill:#FAD,stroke:#333,stroke-width:2px;
    classDef core fill:#BBF,stroke:#333,stroke-width:2px;
    classDef map fill:#BFB,stroke:#333,stroke-width:2px;
    classDef ui fill:#FBB,stroke:#333,stroke-width:2px;
    classDef ext fill:#FF9,stroke:#333,stroke-width:2px,stroke-dasharray:5,5;
    classDef test fill:#9FF,stroke:#333,stroke-width:2px,stroke-dasharray:5,5;

    click CP1 "https://github.com/afforix/therion/blob/master/thinput.cxx"
    click CP2 "https://github.com/afforix/therion/blob/master/thparse.cxx"
    click LOCH "https://github.com/afforix/therion/blob/master/loch/lxRender.cxx"
    click MPOST "https://github.com/afforix/therion/tree/master/mpost/"
    click XTH "https://github.com/afforix/therion/tree/master/xtherion/"
    click LOCH_UI "https://github.com/afforix/therion/blob/master/loch/lxOptDlg.cxx"
    click BS "https://github.com/afforix/therion/blob/master/CMakeLists.txt"
    click POLY "https://github.com/afforix/therion/tree/master/extern/poly2tri/"
    click QH "https://github.com/afforix/therion/tree/master/extern/quickhull/"
    click SH "https://github.com/afforix/therion/tree/master/extern/shapelib/"
    click CATCH "https://github.com/afforix/therion/tree/master/extern/catch2"
    click TEST "https://github.com/afforix/therion/blob/master/utest-main.cxx"
    click GITHUB "https://github.com/afforix/therion/tree/master/.github/workflows/"
```
