# cable-robots/cdpyr architecture

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

- Interactive diagram: https://gitdiagram.com/cable-robots/cdpyr
- Repository: https://github.com/cable-robots/cdpyr

## Overview

##### Project type and purpose
- This is a pure-Python, open-source library (cdpyr) for designing, analyzing, and simulating cable-driven parallel robots.
- There is no “frontend/backend” UI; it exposes an API to load robot specifications, perform kinematic/dynamic analyses, and render results.

##### File structure
- Top-level: packaging config (`setup.py`, `pyproject.toml`), CI (`.travis.yml`, `gitlab-ci.yml`, `ci/`), docs (`docs/`), tests (`tests/`).
- `src/cdpyr/` contains core packages:
- cdpyr.robot: domain model of robot components (cables, pulleys, frames, motors)
- cdpyr.kinematics & cdpyr.mechanics: coordinate transforms, inertial calculations
- cdpyr.analysis: layered analysis engines (archetype, kinematics, dynamics, criterion, stiffness, workspace, force distribution)
- cdpyr.stream: parsers for JSON/XML/YAML and TwinCAT data
- cdpyr.schema & cdpyr.validator: (de)serialization and data validation
- cdpyr.visualization: plug-in engines (Mayavi, Plotly) to render models and results

##### README for additional insights
- Confirms it’s a Python 3 package published on PyPI.
- No built-in UI—users import the library and call its API.
- Testing via pytest and tox; docs on readthedocs.

a. Main components (group by package):
1. Data Input & Parsing
- XML/JSON/YAML parsers (`cdpyr.stream.parser.*`)
- TwinCAT parser
2. Domain Model
- Robot definitions (`cdpyr.robot.*`)
- Geometry primitives (`cdpyr.geometry.*`)
3. Core Computation
- Kinematics & Mechanics (`cdpyr.kinematics`, `cdpyr.mechanics`)
- Analysis engines (`cdpyr.analysis.*`)
4. Schema & Validation
- Pydantic-style schemas (`cdpyr.schema.*`)
- Validators (`cdpyr.validator.*`)
5. Visualization
- Engine abstractions (`cdpyr.visualization.engine.*`)
- Concrete backends (Mayavi, Plotly)
6. Infrastructure
- Helpers, mixins, base classes (`cdpyr.helper`, `cdpyr.mixin`, `cdpyr.base`)
- CI, tests, docs (peripheral)

b. Relationships and interactions
- Parsers read external specs → emit Domain Model objects
- Domain Model feeds Geometry & Kinematics modules → produce transformation matrices, inertias
- Analysis engines consume models plus kinematic/dynamic outputs → compute performance metrics (workspace, stiffness, singularities, force distribution)
- Results and models pass through Schema & Validator for export or API output
- Visualization engines subscribe to model + results to render graphs or 3D scenes

c. Architectural patterns & design principles
- Layered architecture (Input → Model → Compute → Output)
- Plugin-style extensibility: new `analysis.archetype` or `criterion` classes drop into an import folder
- Separation of concerns: parsing, computation, serialization, and rendering are isolated

d. Key technologies & frameworks
- Python 3, NumPy (linear algebra), SciPy (optional), pytest/tox for testing
- Data serialization (JSON, XML, YAML), Pydantic-style schema
- Visualization via Mayavi and Plotly

## Diagram (Mermaid)

```mermaid
graph TB
    %% Nodes
    ExternalSpec["External Robot Specs"]:::external
    Parsing["Data Input & Parsing<br/>(XML/JSON/YAML, TwinCAT)"]:::input
    DomainModelRobot["Robot Definitions"]:::core
    DomainModelGeometry["Geometry Primitives"]:::core
    Kinematics["Kinematics Module"]:::compute
    Mechanics["Mechanics Module"]:::compute
    Analysis["Analysis Engines"]:::compute
    Schema["Schema & Serialization"]:::infra
    Validator["Data Validation"]:::infra
    Visualization["Visualization Engines<br/>(Mayavi, Plotly)"]:::viz
    Infrastructure["Infrastructure Helpers & Mixins"]:::infra

    %% Pipeline Flow
    ExternalSpec -->|"spec files"| Parsing
    Parsing -->|"RobotSpec → RobotObject"| DomainModelRobot
    Parsing -->|"GeometrySpec → ShapeObject"| DomainModelGeometry
    DomainModelRobot -->|"Frames, Cables"| Kinematics
    DomainModelGeometry -->|"Primitives"| Mechanics
    Kinematics -->|"TransformationMatrix"| Analysis
    Mechanics -->|"InertiaProperties"| Analysis
    Analysis -->|"ComputedMetrics"| Schema
    Schema -->|"SerializedData"| Validator
    Validator -->|"ValidatedOutput"| Visualization

    %% Support Relationships
    Infrastructure -.-> Parsing
    Infrastructure -.-> DomainModelRobot
    Infrastructure -.-> DomainModelGeometry
    Infrastructure -.-> Analysis
    Infrastructure -.-> Visualization

    %% Click Events
    click Parsing "https://github.com/cable-robots/cdpyr/tree/master/src/cdpyr/stream/"
    click DomainModelRobot "https://github.com/cable-robots/cdpyr/tree/master/src/cdpyr/robot/"
    click DomainModelGeometry "https://github.com/cable-robots/cdpyr/tree/master/src/cdpyr/geometry/"
    click Kinematics "https://github.com/cable-robots/cdpyr/tree/master/src/cdpyr/kinematics/"
    click Mechanics "https://github.com/cable-robots/cdpyr/tree/master/src/cdpyr/mechanics/"
    click Analysis "https://github.com/cable-robots/cdpyr/tree/master/src/cdpyr/analysis/"
    click Schema "https://github.com/cable-robots/cdpyr/tree/master/src/cdpyr/schema/"
    click Validator "https://github.com/cable-robots/cdpyr/tree/master/src/cdpyr/validator/"
    click Visualization "https://github.com/cable-robots/cdpyr/tree/master/src/cdpyr/visualization/"
    click Infrastructure "https://github.com/cable-robots/cdpyr/tree/master/src/cdpyr/helper/"

    %% Styles
    classDef external fill:#ddeeff,stroke:#336699,stroke-width:2px;
    classDef input fill:#ccffcc,stroke:#2d882d,stroke-width:2px;
    classDef core fill:#cce5ff,stroke:#3366cc,stroke-width:2px;
    classDef compute fill:#ffd699,stroke:#cc6600,stroke-width:2px;
    classDef viz fill:#e5ccff,stroke:#9933cc,stroke-width:2px;
    classDef infra fill:#f2f2f2,stroke:#8c8c8c,stroke-width:2px;
```
