# suratlayek/path-interpolator architecture

> Architecture diagram of the GitHub repository suratlayek/path-interpolator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/suratlayek/path-interpolator
- Repository: https://github.com/suratlayek/path-interpolator

## Overview

1. **What this repository is**
   - A **desktop Python GUI application** for geometric path processing, not a web service.
   - The core workflow is: **load coordinate file → apply offset/buffer → interpolate points at fixed spacing → preview result → save a new output file**.

2. **Primary runtime entry point**
   - `main.py` is the app launcher and likely starts the Qt event loop.
   - `interface.py` is the main application module where UI behavior, file handling, and path-processing orchestration most likely live.

3. **UI construction and presentation**
   - `Assets/interface.ui` is a Qt Designer file, so the window layout is defined declaratively and then loaded or compiled into the Python app.
   - `Assets/Adaptic.qss` provides the application theme/styling, giving the GUI a consistent dark look.
   - This means the visual layer is separated from the processing logic rather than being hand-built entirely in code.

4. **User input boundary**
   - The app accepts coordinate files via **browse or drag-and-drop**.
   - Supported file types in the README are `.txt`, `.tpl`, and `.dat`.
   - The input format is simple text with **space-separated X and Y values per line**, which becomes the raw data boundary for the processing pipeline.

5. **Geometry processing subsystem**
   - The main computational features are:
     - **Path offsetting** using a buffer-like operation, with positive values expanding the path and negative values contracting it.
     - **Interpolation** of points at a user-defined spacing `r` along the resulting path length.
   - The README explicitly ties offsetting to **Shapely buffers**, so the geometry engine is centered on Shapely-style planar geometry operations.

6. **Visualization subsystem**
   - The app includes a **live preview plot** powered by `pyqtgraph`.
   - The plot is used to compare the **original path** and the **processed/interpolated path**, which makes the visualization layer a distinct consumer of the processed geometry output.

7. **Output flow**
   - After generation, the tool writes a new file with an `_interpolated` suffix.
   - This makes file export part of the main processing pipeline, not a separate reporting step.
   - The output is likely another plain coordinate file, matching the app’s text-based input style.

8. **Project packaging and dependency management**
   - `pyproject.toml` and `uv.lock` indicate the project is managed with **uv**, so dependency resolution and environment setup are centralized there.
   - `.python-version` suggests the repo pins a specific Python runtime version.
   - This is a standard desktop-app packaging setup rather than a service deployment model.

9. **Distribution and release boundary**
   - The README references a standalone Windows installer `.exe`, implying the app is also packaged for non-Python end users.
   - That installer is a distribution artifact; it is not part of the runtime architecture inside the repository tree.

10. **Static/documentation assets**
   - `index.html` appears to be a static page or auxiliary artifact rather than core application logic.
   - `README.md` acts as the primary usage and workflow documentation.

11. **Architectural boundaries to draw**
   - **Input layer**: file selection / drag-drop and parsing of text coordinates.
   - **UI layer**: Qt window, controls, styling, and interaction.
   - **Geometry engine**: offset and interpolation calculations.
   - **Visualization layer**: pyqtgraph preview of original vs transformed paths.
   - **Persistence layer**: generation of the `_interpolated` output file.

12. **Overall structure**
   - This is a **single-user desktop application** with a fairly tight loop between UI and computation.
   - There is no evidence of a server, database, or networked backend.
   - The important diagram should show a **Qt-based front end** orchestrating a **geometry-processing core** and a **plotting/output path**.

Main entry points: [`interface.py`](https://github.com/suratlayek/path-interpolator/blob/master/interface.py) (App Logic), [`pyproject.toml`](https://github.com/suratlayek/path-interpolator/blob/master/pyproject.toml) (Project Config), [`main.py`](https://github.com/suratlayek/path-interpolator/blob/master/main.py) (Launcher), [`.python-version`](https://github.com/suratlayek/path-interpolator/blob/master/.python-version) (Python Pin)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_ui["Desktop UI"]
  node_main_py["Launcher<br/>Qt entrypoint<br/>[main.py]"]
  node_interface_py["App Logic<br/>Qt controller<br/>[interface.py]"]
  node_preview_plot["Preview Plot<br/>pyqtgraph view"]
end

subgraph group_group_core["Processing Core"]
  node_input_parser["Input Parse<br/>text coordinates"]
  node_offset_engine{{"Offset Path<br/>geometry buffer"}}
  node_interp_engine{{"Interpolate<br/>fixed spacing"}}
  node_output_writer["Export File<br/>coordinate output"]
end

subgraph group_group_assets["Assets"]
  node_ui_file["Window Layout<br/>Qt Designer UI<br/>[interface.ui]"]
  node_theme_file["Theme<br/>QSS stylesheet<br/>[Adaptic.qss]"]
end

subgraph group_group_packaging["Project Setup"]
  node_pyproject["Project Config<br/>uv/pyproject<br/>[pyproject.toml]"]
  node_uvlock["Locked Deps<br/>uv lockfile<br/>[uv.lock]"]
  node_pythonver["Python Pin<br/>runtime version<br/>[.python-version]"]
end

node_main_py -->|"launches"| node_interface_py
node_interface_py -->|"loads UI"| node_ui_file
node_interface_py -->|"applies theme"| node_theme_file
node_interface_py -->|"reads files"| node_input_parser
node_input_parser -->|"path data"| node_offset_engine
node_offset_engine -->|"processed path"| node_interp_engine
node_interp_engine -->|"renders"| node_preview_plot
node_input_parser -->|"original path"| node_preview_plot
node_interp_engine -->|"exports"| node_output_writer
node_interface_py -->|"updates view"| node_preview_plot
node_pyproject -->|"resolves"| node_uvlock
node_pythonver -->|"pins runtime"| node_pyproject

click node_main_py "https://github.com/suratlayek/path-interpolator/blob/master/main.py"
click node_interface_py "https://github.com/suratlayek/path-interpolator/blob/master/interface.py"
click node_ui_file "https://github.com/suratlayek/path-interpolator/blob/master/Assets/interface.ui"
click node_theme_file "https://github.com/suratlayek/path-interpolator/blob/master/Assets/Adaptic.qss"
click node_pyproject "https://github.com/suratlayek/path-interpolator/blob/master/pyproject.toml"
click node_uvlock "https://github.com/suratlayek/path-interpolator/blob/master/uv.lock"
click node_pythonver "https://github.com/suratlayek/path-interpolator/blob/master/.python-version"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main_py,node_interface_py,node_preview_plot toneBlue
class node_input_parser,node_offset_engine,node_interp_engine,node_output_writer toneAmber
class node_ui_file,node_theme_file toneMint
class node_pyproject,node_uvlock,node_pythonver toneRose
```

## Components

### Desktop UI

Qt window, controls, styling, and user interaction.

- [Launcher](https://github.com/suratlayek/path-interpolator/blob/master/main.py): Qt entrypoint · Starts the desktop application and event loop. · `main.py`
- [App Logic](https://github.com/suratlayek/path-interpolator/blob/master/interface.py): Qt controller · Coordinates UI behavior, file handling, processing, and preview updates. · `interface.py`
- **Preview Plot**: pyqtgraph view · Displays original and processed paths for live comparison.

### Processing Core

Geometry transformation and file pipeline.

- **Input Parse**: text coordinates · Reads space-separated X/Y coordinate lines from supported files.
- **Offset Path**: geometry buffer · Expands or contracts the path using buffer-like planar geometry operations.
- **Interpolate**: fixed spacing · Generates points along the processed path at user-defined spacing.
- **Export File**: coordinate output · Writes the processed coordinates to a new file with an interpolated suffix.

### Assets

Designer and theme files used by the GUI.

- [Window Layout](https://github.com/suratlayek/path-interpolator/blob/master/Assets/interface.ui): Qt Designer UI · Declarative definition of the application window and controls. · `Assets/interface.ui`
- [Theme](https://github.com/suratlayek/path-interpolator/blob/master/Assets/Adaptic.qss): QSS stylesheet · Visual styling for the desktop interface. · `Assets/Adaptic.qss`

### Project Setup

Python runtime pinning and dependency management.

- [Project Config](https://github.com/suratlayek/path-interpolator/blob/master/pyproject.toml): uv/pyproject · Defines package metadata and dependencies. · `pyproject.toml`
- [Locked Deps](https://github.com/suratlayek/path-interpolator/blob/master/uv.lock): uv lockfile · Pins resolved dependency versions for reproducible installs. · `uv.lock`
- [Python Pin](https://github.com/suratlayek/path-interpolator/blob/master/.python-version): runtime version · Pins the Python version used by the app. · `.python-version`

## Connections

- Launcher → App Logic: launches · Main module starts the app controller and Qt loop.
- App Logic → Window Layout: loads UI · The interface is built from the Qt Designer layout.
- App Logic → Theme: applies theme · Stylesheet is used to skin the window.
- App Logic → Input Parse: reads files · User-selected or dropped coordinate files are parsed into path data.
- Input Parse → Offset Path: path data · Parsed coordinates feed the geometric transformation stage.
- Offset Path → Interpolate: processed path · Offset result is sampled at fixed spacing.
- Interpolate → Preview Plot: renders · Interpolated output is visualized alongside the original path.
- Input Parse → Preview Plot: original path · Raw geometry is also shown in the preview.
- Interpolate → Export File: exports · Final coordinates are written to a new output file.
- App Logic → Preview Plot: updates view · UI orchestrates live plot refreshes during interaction.
- Project Config → Locked Deps: resolves · Project configuration is locked into reproducible dependency versions.
- Python Pin → Project Config: pins runtime · The project targets a specific Python version.