Metadata-Version: 2.4
Name: draw-ui
Version: 0.1.1
Summary: Declarative 2D Canvas, Layout, Physics and UI Library built on PySide6
Author: Draw Framework Team
License-Expression: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PySide6>=6.5.0
Requires-Dist: numpy>=1.20.0
Requires-Dist: PyOpenGL>=3.1.5
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Dynamic: license-file

# Draw-lib 🎨⚡

[![PyPI version](https://img.shields.io/badge/pypi-v0.1.0-blue.svg)](https://pypi.org/project/draw-lib/)
[![Python Versions](https://img.shields.io/badge/python-3.9%20%7C%203.10%20%7C%203.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue)](https://python.org)
[![PySide6](https://img.shields.io/badge/Qt6-PySide6-brightgreen.svg)](https://pypi.org/project/PySide6/)
[![OpenGL](https://img.shields.io/badge/Hardware%20Accel-OpenGL%203.3+-orange.svg)](https://pypi.org/project/PyOpenGL/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

> **Draw-lib** is a high-performance, declarative 2D Canvas, Relative Layout, Procedural Motion Physics & UI framework built on **PySide6 (Qt 6)** and **OpenGL**.
>
> Designed for modern reactive user interfaces, scientific visualizations, vector animation, and procedural 2D physics simulations with minimal boilerplate and 60–120+ FPS performance.

---

## 🌟 Key Highlights

- **Declarative Vector Canvas (`Draw.shape`)**: Construct geometric primitives, multi-segment polygons, radial arrays, starbursts, bezier curves, mesh warps, and gradient fills using simple Python dictionaries.
- **Hardware OpenGL Acceleration (`Draw.super`)**: Dynamic GPU geometry batching with GLSL shaders capable of driving thousands of kinetic shapes at locked 60–120+ FPS.
- **Visibility Optimization Engine (`Draw.veo`)**: 5-phase spatial hierarchy, viewport bounding-box culling, and 2D occlusion culling that drastically cuts draw calls.
- **Procedural Motion Physics (`Draw.motion`)**: 38 built-in procedural motion presets, spring mechanics, harmonic oscillations, kinetic damping, orbital paths, and custom timelines.
- **Physics Links & Joints (`Draw.connectors` & `Draw.senses`)**: Distance locks, elastic springs, pendulums, verlet ropes, drag physics, and real-time bounding collision sensing.
- **Declarative Graphing & Data Visualizations (`Draw.graph`)**: 11 out-of-the-box chart types (Bar, Line, Area, Scatter, Pie, Donut, Radar, Spider, Polar) with interactive legends, tooltips, and live streaming data.
- **Reactive State (`Draw.live`)**: High-speed reactive variables with bi-directional bindings and sub-millisecond propagation across canvas elements and input fields.
- **Relative Room Layout Engine (`Draw.room` & `Draw.table`)**: Responsive grid layouts, cell offsets, anchor snapping, and adaptive container boundaries.
- **Hybrid Native Controls (`Draw.widget`)**: Seamlessly embed native Qt widgets (Buttons, Sliders, LineEdits, ComboBoxes, Checkboxes, FileTree) directly into declarative scenes.
- **Built-in Diagnostics & Profiler (`Draw.profiler`, `Draw.debug`)**: Real-time FPS overlay, frame budget breakdown, watchdog thread monitoring, and crash protection.

---

## 📦 Installation

### Standard Installation

Install via pip:

```bash
pip install draw-lib
```

### From Source (Development / Editable)

Clone the repository and install in editable mode:



### Dependencies
- Python `>= 3.9`
- `PySide6 >= 6.5.0`
- `numpy >= 1.20.0`
- `PyOpenGL >= 3.1.5`

---

## 🚀 Quickstart

### 1. Rotating Geometric Hexagon

```python
import Draw

# Initialize a window
Draw.window(tag="main", title="Draw Quickstart", width=800, height=600, background_color="#0F172A")

# Add a declarative rotating hexagon with gradient
Draw.shape(
    display="main",
    shape=[{
        "ip": "hex_core",
        "vertices": 6,
        "size": [160, 160],
        "align": "center",
        "color": "#38BDF8",
        "stroke_color": "#0284C7",
        "stroke_width": 3,
        "rotation": "time * 60"
    }]
)

# Start event loop
Draw.window.run("main")
```

---

### 2. Interactive Physics Springs & Motion

```python
import Draw

Draw.window(tag="physics_demo", width=900, height=700, background_color="#1E1E2E")

# Create anchor and bob
Draw.shape(display="physics_demo", shape=[
    {"ip": "anchor", "type": "circle", "size": [30, 30], "align": "center", "y": 150, "color": "#F38BA8"},
    {"ip": "bob", "type": "circle", "size": [50, 50], "align": "center", "y": 400, "color": "#89B4FA", "drag": True}
])

# Connect anchor and bob with an elastic spring
Draw.connectors.spring(
    display="physics_demo",
    source="anchor",
    target="bob",
    stiffness=0.08,
    damping=0.85,
    stroke_color="#A6ADC8",
    stroke_width=2
)

Draw.window.run("physics_demo")
```

---

### 3. Declarative Real-Time Charts

```python
import Draw

Draw.window(tag="dashboard", width=850, height=550, background_color="#181825")

Draw.graph(
    display="dashboard",
    type="bar",
    data=[45, 82, 60, 95, 120, 75, 110],
    labels=["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"],
    color="#A6E3A1",
    align="center",
    width=650,
    height=350,
    animate=True
)

Draw.window.run("dashboard")
```

---

## 🏛️ Core Architecture & Modules

| Module | Access Point | Description |
| :--- | :--- | :--- |
| **Window** | `Draw.window` | Multi-window orchestration, transparency, frameless modes, and resize hooks. |
| **Shapes** | `Draw.shape` / `Draw.shapes` | Declarative 2D primitives, polygons, bezier paths, gradients, and hitboxes. |
| **Motion** | `Draw.motion`, `Draw.timeline` | 38 procedural physics routines, harmonic bounds, springs, and orbital mechanics. |
| **Connectors** | `Draw.connectors`, `Draw.senses` | Physics springs, ropes, pendulums, joints, and dynamic collision sensing. |
| **Graphing** | `Draw.graph` | 11 declarative chart types (bar, line, scatter, pie, donut, radar, spider). |
| **Live State** | `Draw.live`, `Draw.input_field` | High-speed 60Hz reactive variable bindings with bidirectional propagation. |
| **Super Engine** | `Draw.super`, `Draw.super_mode` | Hardware-accelerated OpenGL 3.3+ batch renderer with dynamic GLSL pipelines. |
| **VEO Engine** | `Draw.veo` | Visibility Engine Optimization with 5-phase spatial culling & dust removal. |
| **Room Layout** | `Draw.room`, `Draw.table`, `Draw.grid` | Responsive relative layout containers, anchor positioning, and cell offsets. |
| **Native Widgets**| `Draw.widget`, `Draw.box` | Embedded PySide6 native controls (buttons, sliders, inputs, comboboxes). |
| **Typography** | `Draw.text`, `Draw.lineedit` | Vector typography, animated cursor caret, and rich text editors. |
| **Screen Surface**| `Draw.screen` | Pixel buffers, custom render passes, and high-frequency raster surfaces. |
| **Diagnostics** | `Draw.debug`, `Draw.profiler` | Watchdog thread supervisor, frame latency meters, and diagnostic telemetry. |

---

## 📁 Repository Structure

```
Draw-project/
├── pyproject.toml              # PEP 517/518/621 package metadata & configuration
├── setup.py                    # Backward compatibility & editable install entry point
├── README.md                   # Project documentation & reference manual
├── LICENSE                     # MIT Open Source License
├── requirements.txt            # Core production dependencies
├── requirements-dev.txt        # Development, testing, and packaging tools
├── MANIFEST.in                 # Distribution manifest rules
├── .gitignore                  # Git tracking exclusion rules
│
├── __init__.py                 # Draw package root, lazy imports & public API exports
├── _window.py                  # Window manager & PySide6 application lifecycle
├── _shapes.py                  # Declarative vector shapes & geometry primitives
├── _super.py                   # OpenGL hardware acceleration renderer
├── _veo.py                     # Visibility Optimization Engine (spatial culling)
├── _motion.py                  # Procedural motion presets & animation timelines
├── _connectors.py              # Physics links, springs, ropes, and pendulums
├── _graph.py                   # Declarative graphing & charting engine
├── _live.py                    # 60Hz reactive state bindings
├── _room.py                    # Relative room layout system
├── _native.py                  # Native PySide6 widget integration
├── _text.py                    # Typography & caret text input controls
├── _screen.py                  # High-speed raster screen surface
├── _profiler.py                # Frame latency & performance metrics
├── ...                         # Core engine modules
│
├── examples/                   # Standalone, runnable showcase applications
│   ├── dodge_game.py           # Complete arcade dodge game with HUD & particles
│   ├── app_three_graph_comparison.py # Multi-graph visual analytics dashboard
│   ├── test_super_interactive_dashboard.py # 120 FPS OpenGL hardware stress test
│   └── test_scroller_showcase.py # Kinetic smooth scroller showcase
│
├── tests/                      # Comprehensive pytest test suite
│   ├── test_super_opengl.py    # OpenGL hardware acceleration tests
│   ├── test_veo.py             # Spatial culling engine verification
│   ├── test_screen.py          # Screen surface buffer tests
│   └── test_watchdog_fixes.py  # Thread stability & watchdog tests
│
└── full_documentation/         # In-depth module-by-module markdown specifications
    ├── WINDOW_MODULE_DOCUMENTATION.md
    ├── SHAPE_MODULE_DOCUMENTATION.md
    ├── SUPER_ENGINE_DOCUMENTATION.md
    ├── VEO_MODULE_DOCUMENTATION.md
    ├── MOTION_MODULE_DOCUMENTATION.md
    └── GRAPH_MODULE_DOCUMENTATION.md
```

---

## 🧪 Running Tests

Run the complete test suite using `pytest`:

```bash
# Run all unit and integration tests
pytest

# Run tests with verbose output
pytest -v

# Run OpenGL & hardware-acceleration tests
pytest tests/test_super_opengl.py

# Run spatial culling engine tests
pytest tests/test_veo.py
```

---

## 💡 Note from the Solo Developer & Vibe Coding Story

> *"I love cool animations, graphics, and cool UI designs — and I wanted to see if we could make UI design truly easy, declarative, and fun like CSS."*

Hi! **Draw-lib** was created by a passionate **16-year-old solo developer** who wanted to make desktop UI and graphics design in Python feel as natural, declarative, and expressive as modern CSS without the traditional hundreds of lines of Qt/GUI boilerplate.

### 🤖 Built with Vibe Coding
This library is a product of **vibe coding** and creative AI-assisted engineering. The architecture, declarative CSS-like syntax, and feature concepts were conceived by the solo creator, with artificial intelligence used to implement, iterate, and refine the extensive multi-module codebase.

### 💖 A Humble Note on Maintenance
Because this entire project is built and maintained by a **solo developer**:
- **I cannot be attentive to every single edge case, bug, platform quirk, or setup detail at all times.**
- Some features are polished while others are experimental.
- Your patience, constructive feedback, and community contributions mean the world. If you spot a bug or have an idea, please open an issue or submit a pull request!

---

## 🤝 Contributing

Contributions are warmly welcome!
1. Fork the repository (`https://github.com/shubhrtx-beep/Draw-lib`)
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

---

## 📄 License

This project is licensed under the **MIT License** — see the [LICENSE](LICENSE) file for details.

