# solalbaudoincs/tipe architecture

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

- Interactive diagram: https://gitdiagram.com/solalbaudoincs/tipe
- Repository: https://github.com/solalbaudoincs/tipe

## Overview

- Core Geometry Module:
– Represented by the file "polygone.py", which defines the essential data structures (Point, Vecteur, Segment, and Polygone) for computational geometry.
- Algorithm Modules:
– "decompositionConvexe.py": Implements the convex decomposition algorithm based on Keil’s method using dynamic programming.
– "decompositionEtoile.py": Contains the analogous algorithm for decomposing into “polygones étoilés.”
– Additionally, "decomposition_convexe_naive.py" might be noted as an alternate (or baseline) implementation.
- Utility Functions:
– "helpers.py": Contains generic utility functions (example: a dichotomic search function) to support various computational processes.
- Visualization and Debug Components:
– "demo.py": A graphical application interface that allows interactive experimentation with the decomposition algorithms.
- Data Analysis and Notebooks:
– "src/notebooks": Contains Jupyter notebooks (e.g., "Analyse plan de voirie paris.ipynb" and debug notebooks) that demonstrate how the algorithms are applied to real-world data (such as the Paris road plan in "plan-de-voirie-chaussees-paris.geojson").
- External Documentation and Presentation Materials:
– Documents such as "paper.pdf", "MCOT.pdf", and "PPT_TIPE.pdf" provide background, theoretical basis, and presentation context for the project.

##### Out the Relationships and Data Flows
- Data Flow and Module Interaction:
– User Interaction: The user starts by interacting with the demo interface (demo.py), which serves as the front end.
– Input → Data Structures: The demo collects or simulates polygon data; these are translated into geometric objects via the classes from "polygone.py."
– Algorithm Invocation: The geometric objects are then processed by calls to the decomposition algorithms (either convex in "decompositionConvexe.py" or étoilé in "decompositionEtoile.py"). Note the dynamic programming approaches and their potential computational complexity (e.g., O(n^7)).
– Visualization: Once the computation is complete, the results are passed back to the visualization module ("affichage.py") to display the resulting decomposition.
– Analysis: Separately, Jupyter notebooks connect to the same underlying modules to process external geospatial data (from the geojson file) and to analyze algorithm performance.

##### Architectural Patterns and Design Principles
- Modularity and Separation of Concerns: The project is clearly segmented into geometric modeling, algorithmic processing, and visualization with distinct modules for each.
- Reusability: Core components (e.g., the geometry classes) are reused across both algorithm implementations and visualization routines.
- Extensibility: The structured layout (with notebooks for analysis and a demo application) allows new algorithms or additional visualization features to be integrated later.

– User/Analyst at one end interfacing with the Demo Application and Jupyter Notebooks.
– Core System Modules (split into “Geometry”, “Algorithms”, and “Visualization”) in the center.
– External Data Sources and Documentation (geojson file, PDFs) connected appropriately.
– Detailing the internal structure within the “Algorithms” block, listing out convex and étoilé decomposition as separate but related modules.
– Including the supporting utility functions available in "helpers.py."
– Demonstrating the directory layout where relevant if it helps show organization.
– Data flow (input → processing → output)
– Module dependencies (e.g., The demo application depends on both the algorithm and visualization components.)

##### Final Advice
- Be as detailed as possible: Do not shy away from showing even minor modules such as “affichage.py” and “helpers.py” to give a complete picture.
- Relevant performance annotations (e.g., run-time expectations for decomposition algorithms) where appropriate.

## Diagram (Mermaid)

```mermaid
flowchart TD
    User["User/Analyst"]:::user
    Demo["Demo Application (Interactive GUI)"]:::frontend
    Notebooks["Jupyter Notebooks"]:::analysis
    Geometry["Core Geometry (polygone.py)"]:::backend
    Helpers["Utility Functions (helpers.py)"]:::backend
    Visualization["Visualization Module (affichage.py)"]:::frontend
    Gifs["Animated Visualization Assets"]:::frontend
    Docs["External Documentation and Presentation"]:::external
    Paper["paper.pdf"]:::external
    MCOT["MCOT.pdf"]:::external
    PPT["PPT_TIPE.pdf"]:::external

    subgraph "Algorithm Modules"
        Convex["Convex Decomposition (decompositionConvexe.py)"]:::backend
        Etoile["Étoilé Decomposition (decompositionEtoile.py)"]:::backend
        Naive["Naive Convex Decomposition (decomposition_convexe_naive.py)"]:::backend
    end

    %% User interactions
    User -->|"UI_interact"| Demo
    User -->|"Analysis_query"| Notebooks
    User -->|"AccessDocs"| Docs

    %% Frontend to Backend initiation
    Demo -->|"Collect_polygon_data"| Geometry
    Notebooks -->|"Load&Analyze"| Geometry

    %% Geometry invokes algorithm modules
    Geometry -->|"Invoke_algorithms"| Convex
    Geometry -->|"Invoke_algorithms"| Etoile
    Geometry -->|"Invoke_algorithms"| Naive

    %% Utility functions support algorithms
    Helpers -->|"Support"| Convex
    Helpers -->|"Support"| Etoile
    Helpers -->|"Support"| Naive

    %% Algorithm output to visualization
    Convex -->|"Process_results"| Visualization
    Etoile -->|"Process_results"| Visualization
    Naive -->|"Process_results"| Visualization

    %% Visualization renders animated graphics
    Visualization -->|"Render_graphics"| Gifs

    %% Notebooks also visualize results
    Notebooks -->|"Visualize_results"| Visualization

    %% External documentation details
    Docs -->|"Includes"| Paper
    Docs -->|"Includes"| MCOT
    Docs -->|"Includes"| PPT

    %% Click Events
    click Demo "https://github.com/solalbaudoincs/tipe/blob/main/src/demo.py"
    click Notebooks "https://github.com/solalbaudoincs/tipe/tree/main/src/notebooks"
    click Geometry "https://github.com/solalbaudoincs/tipe/blob/main/src/polygone.py"
    click Convex "https://github.com/solalbaudoincs/tipe/blob/main/src/decompositionConvexe.py"
    click Etoile "https://github.com/solalbaudoincs/tipe/blob/main/src/decompositionEtoile.py"
    click Naive "https://github.com/solalbaudoincs/tipe/blob/main/src/decomposition_convexe_naive.py"
    click Helpers "https://github.com/solalbaudoincs/tipe/blob/main/src/helpers.py"
    click Visualization "https://github.com/solalbaudoincs/tipe/blob/main/src/affichage.py"
    click Gifs "https://github.com/solalbaudoincs/tipe/tree/main/src/gifs"
    click Paper "https://github.com/solalbaudoincs/tipe/blob/main/paper.pdf"
    click MCOT "https://github.com/solalbaudoincs/tipe/blob/main/MCOT.pdf"
    click PPT "https://github.com/solalbaudoincs/tipe/blob/main/PPT_TIPE.pdf"

    %% Styles
    classDef user fill:#ffcc99,stroke:#d97600,stroke-width:2px;
    classDef frontend fill:#add8e6,stroke:#00008b,stroke-width:2px;
    classDef backend fill:#90ee90,stroke:#006400,stroke-width:2px;
    classDef analysis fill:#ffe4e1,stroke:#cd5c5c,stroke-width:2px;
    classDef external fill:#dddddd,stroke:#555555,stroke-width:2px;
```
