Metadata-Version: 2.4
Name: voidmesh
Version: 0.1.0
Summary: Live force-directed graphs and systematic trees for Python
Keywords: graph,visualization,nodes,physics,canvas
Author: Aahan
Author-email: Aahan <188063520+aahan0511@users.noreply.github.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Dist: pygame-ce>=2.5.8
Requires-Python: >=3.14
Description-Content-Type: text/markdown

# Voidmesh

A small Python 3.14 library for building and displaying live, Obsidian-inspired
force-directed graphs. Values are rendered inside draggable rounded nodes;
links act like springs; gravity and repulsion settle the graph into place.

## Install

```console
uv add voidmesh
```

For local development:

```console
uv sync
uv run voidmesh-demo
```

## Quick start

```python
from voidmesh import Canvas

canvas = Canvas(title="My graph", grid=True)
python = canvas.add_node("Python", color="#fbbf24")
graphs = canvas.add_node("Graphs", color="#a78bfa")
edge = canvas.link(python, graphs, color="#38bdf8")

# Keep executing code while the window stays responsive.
canvas.show(block=False)

canvas.update_node(graphs, value="Live graphs", color="#34d399")
canvas.update_link(edge, color="#fb7185", elasticity=0.06)
canvas.wait()  # Keep the script alive until the window is closed.
```

All mutating methods update an open window immediately:

```python
third = canvas.add_node("New")
canvas.relink(edge, target=third)
canvas.unlink(edge)  # or canvas.unlink(python, third)
canvas.delete_node(graphs)  # also deletes attached links
canvas.clear()
canvas.close()
```

Call `canvas.show()` without arguments for a blocking window. Drag nodes with
the left mouse button, pan with the right mouse button, zoom with the wheel, and
press Escape to close. `fixed=True` pins a node after it is dragged.

The **Controls** panel changes center force, repulsion, link force, and link
distance while the graph is moving. Drag its heading to reposition it, or click
the chevron to collapse it. Press `F` to hide or show the panel and `G` to
toggle the background grid.

Physics and the grid can also be controlled from Python:

```python
canvas.configure_physics(
    center_force=0.2,
    repel_force=8,
    link_force=0.4,
    link_distance=190,
    damping=0.92,
)
canvas.toggle_grid(True)
```

The same values can be passed to `Canvas(...)`. Set `controls=False` for a
minimal window without the controls panel. Controls scale automatically with the
window; use `ui_scale=1.5` (or another positive multiplier) to override their
size on a HiDPI display. Graph zoom and UI scale are intentionally independent.

Switch to a deterministic, physics-free hierarchy with `layout="tree"`, the
Tree button in the panel, or the `T` key. Links are interpreted as parent to
child in this view. See the bundled example:

```console
uv run python examples/tree_view.py
```

Fonts, type size, node padding and roundness, link thickness, and grid color
can be set on `Canvas(...)` or changed live with `configure_style()`.

## Development

```console
uv run pytest
uv run ruff check .
uv build
uv run mkdocs serve
```

Complete documentation lives in [`docs/`](docs/index.md). Build it with
`uv run mkdocs build --strict`.

Voidmesh is licensed under the MIT License.
