# meyerls/pc-skeletor architecture

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

- Interactive diagram: https://gitdiagram.com/meyerls/pc-skeletor
- Repository: https://github.com/meyerls/pc-skeletor

## Overview

##### Project Type & Purpose
- PC Skeletor is a pure-Python algorithmic library (not a web app or microservice) for extracting curve skeletons from 3D point clouds.
- It implements two core algorithms: Laplacian-Based Contraction (LBC) and Semantic LBC (S-LBC), plus helper routines for downloading datasets, sampling, graph extraction, visualization, and export.

##### File Structure Analysis
- Top‐level:
- pc_skeletor/ (core package)
– base.py       : abstract base classes and shared interfaces
– download.py   : Dataset downloader (external data source)
– laplacian.py  : Laplacian matrix computation and contraction solver
– point2skeleton.py : placeholder for future Point2Skeleton algorithm
– utility.py    : sampling, weighting, I/O helpers
– L1.py, __init__.py
- example_tree.py : usage example / entry point for demo
- tests/          : unit tests (test_lbc.py, test_slbs.py)
- setup.py/pyproject.toml/requirements.txt : packaging & dependencies
- .github/workflows : CI pipelines for test & publish
- img/            : illustration assets for README

##### README Insights
- Confirms two primary algorithm classes: LBC and SLBC
- Lists external dependencies: Open3D, numpy, networkx, mistree (MST), robust-laplacians-py

a. Main Components
- Data Source (remote datasets; `Dataset` in download.py)
- Core Algorithm Module
– Laplacian Computation (laplacian.py)
– Contraction Solver (base.py subclasses LBC & SLBC)
– Semantic Weighting (SLBC)
- Sampling & Graph Extraction (utility.py + networkx)
- Visualization & Export (Open3D, gif & file I/O)
- Tests & CI/CD (tests/, GitHub Actions)
- Packaging & Distribution (PyPI, setup.py)
b. Relationships & Data Flows
1. User Code (example_tree.py or consumer code)
→ invokes Dataset.download_semantic_tree_dataset()
→ reads to Open3D point clouds
2. User instantiates LBC or SLBC
→ Core Algorithm calls Laplacian builder → constructs sparse matrix
→ Solver iterates contraction steps → yields contracted skeleton points
3. Skeleton points fed into utility methods
→ farthest-point sampling; networkx MST for topology
4. Graphs & point clouds passed to visualization methods
→ Open3D renderers & gif exporter
5. Exported files written to disk
c. Architectural Patterns
- Modular pipeline: download → preprocess → compute → postprocess → output
- Strategy pattern via base.py → LBC vs. SLBC classes
- Dependency injection for semantic weighting in SLBC
d. Technologies & Frameworks
- Python 3.8+; package managed via setuptools/pyproject.toml
- Open3D for 3D data structures & visualization
- NumPy/SciPy for numeric & sparse linear algebra
- networkx + mistree for graph extraction (MST)
- GitHub Actions for CI and PyPI publishing

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User Entry"
        E[/example_tree.py/]:::entry
        click E "https://github.com/meyerls/pc-skeletor/blob/main/example_tree.py"
    end
    E -->|invoke download| D["Dataset Downloader\n(download.py)"]:::module
    click D "https://github.com/meyerls/pc-skeletor/blob/main/pc_skeletor/download.py"
    D --> RP((Raw PointCloud)):::data
    RP --> LC["Laplacian Computation\n(laplacian.py)"]:::module
    click LC "https://github.com/meyerls/pc-skeletor/blob/main/pc_skeletor/laplacian.py"
    LC --> SM((Sparse Matrix)):::data
    SM --> SOL["Contraction Solver & Strategy\n(base.py)"]:::module
    click SOL "https://github.com/meyerls/pc-skeletor/blob/main/pc_skeletor/base.py"
    SOL --> CP((Contracted PointCloud)):::data
    SOL --> SLC["Semantic LBC Variant\n(L1.py)"]:::module
    click SLC "https://github.com/meyerls/pc-skeletor/blob/main/pc_skeletor/L1.py"
    CP --> SG["Sampling & Graph Extraction\n(utility.py)"]:::module
    click SG "https://github.com/meyerls/pc-skeletor/blob/main/pc_skeletor/utility.py"
    SG --> SKG((Skeleton Graph)):::data
    SKG --> V["Visualization & Export"]:::external
    V --> O((Output Files)):::data

    subgraph "DevOps & Maintenance"
        T["Unit Tests\n(test_lbc.py, test_slbs.py)"]:::devop
        click T "https://github.com/meyerls/pc-skeletor/blob/main/tests/test_lbc.py"
        click T "https://github.com/meyerls/pc-skeletor/blob/main/tests/test_slbs.py"
        W["CI/CD Workflows\n(python-package.yml, python-publish.yml)"]:::devop
        click W "https://github.com/meyerls/pc-skeletor/blob/main/.github/workflows/python-package.yml"
        click W "https://github.com/meyerls/pc-skeletor/blob/main/.github/workflows/python-publish.yml"
        P["Packaging & Distribution\n(setup.py, pyproject.toml, requirements.txt)"]:::devop
        click P "https://github.com/meyerls/pc-skeletor/blob/main/setup.py"
        click P "https://github.com/meyerls/pc-skeletor/blob/main/pyproject.toml"
        click P "https://github.com/meyerls/pc-skeletor/blob/main/requirements.txt"
    end

    classDef module fill:#e0f2e9,stroke:#027f3b,stroke-width:1px;
    classDef data fill:#e8f0fe,stroke:#4285f4,stroke-width:1px;
    classDef external fill:#fff3e0,stroke:#fb8c00,stroke-width:1px;
    classDef entry fill:#f5f5f5,stroke:#9e9e9e,stroke-width:1px;
    classDef devop fill:#f3e5f5,stroke:#8e24aa,stroke-width:1px;
```
