Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
28 commits
Select commit Hold shift + click to select a range
a5d1285
perf: closest() and near() use a matrix of coordinates, not a loop (#74)
petercorke Oct 13, 2026
4d38389
docs(llms): add "when to use it" and recipes, link llms.txt from PyPI
petercorke Oct 15, 2026
fe10d37
fix(plot): default to environment-managed Matplotlib display
huxiaoyi-ovo Oct 19, 2026
749717a
test(plot): verify default and explicit Matplotlib show modes
huxiaoyi-ovo Oct 19, 2026
d720f3e
docs(plot): show graph and path together in scripts
huxiaoyi-ovo Oct 19, 2026
e6b27f7
docs(plot): document block semantics for pgraph users
huxiaoyi-ovo Oct 19, 2026
a5c1744
test(plot): align block contract tests with unittest conventions
huxiaoyi-ovo Oct 21, 2026
4e1c1f9
fix(spatial): handle SE2 angles that round to the period (#86)
Vamsi-2581 Oct 31, 2026
548fb5f
fix: repr(g) is the one-line summary, show() lists the vertices
petercorke Oct 31, 2026
eb5ff7b
refactor: narrow optional edge ends and vertex names with a checked h…
petercorke Oct 31, 2026
347b7c8
chore: housekeeping leftovers from the Codacy cleanup
petercorke Oct 31, 2026
03fdd8b
feat(edge): show ↔ and → between the ends of an edge
petercorke Oct 31, 2026
343a0f2
Merge pull request #87 from petercorke/fix/graph-repr
petercorke Oct 31, 2026
7adc047
Merge branch 'main' into refactor/narrow-with-helpers
petercorke Oct 31, 2026
bffb7be
Merge pull request #88 from petercorke/refactor/narrow-with-helpers
petercorke Oct 31, 2026
0cf0dd0
Merge branch 'main' into chore/housekeeping-leftovers
petercorke Oct 31, 2026
17b8470
Merge pull request #89 from petercorke/chore/housekeeping-leftovers
petercorke Oct 31, 2026
27c41bc
Merge branch 'main' into feat/edge-unicode-arrows
petercorke Oct 31, 2026
bd045d7
test: show() expects the new edge arrow
petercorke Oct 31, 2026
dc3ea70
Merge branch 'main' into docs/llms-when-to-use
petercorke Oct 31, 2026
754ca27
Merge pull request #90 from petercorke/feat/edge-unicode-arrows
petercorke Oct 31, 2026
20d00fe
Merge branch 'main' into docs/llms-when-to-use
petercorke Oct 31, 2026
ffb259d
Merge pull request #77 from petercorke/docs/llms-when-to-use
petercorke Oct 31, 2026
5c9cbbb
Merge branch 'main' into perf/closest-vectorized
petercorke Oct 31, 2026
8d5ba07
Merge pull request #81 from petercorke/perf/closest-vectorized
petercorke Oct 31, 2026
0c33e9b
chore(deps): bump pypa/gh-action-pypi-publish from 1.14.2 to 1.14.3
dependabot[bot] Nov 1, 2026
5d64b2e
Merge pull request #91 from petercorke/dependabot/github_actions/pypa…
github-actions[bot] Nov 1, 2026
998bdfd
Merge upstream and document three-state plotting behaviour
huxiaoyi-ovo Nov 2, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -76,7 +76,7 @@ jobs:
pytest --cov=pgraph --cov-report=xml:coverage.xml
coverage report
- name: Upload coverage to Codecov
uses: codecov/codecov-action@v7
uses: codecov/codecov-action@303a32d7a59b442fa8d48b6a1cc6825c09c847a5 # v7.1.1
with:
files: ./coverage.xml
verbose: true
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/dependabot-auto-merge.yml
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ jobs:
steps:
- name: Dependabot metadata
id: metadata
uses: dependabot/fetch-metadata@v3
uses: dependabot/fetch-metadata@25dd0e34f4fe68f24cc83900b1fe3fe149efef98 # v3.1.0
with:
github-token: "${{ secrets.GITHUB_TOKEN }}"

Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/publish.yml
Original file line number Diff line number Diff line change
Expand Up @@ -110,6 +110,6 @@ jobs:
path: dist

# pinned to a commit, as this action can publish to PyPI; dependabot updates it
- uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
- uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3
with:
skip-existing: true
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
build/
docs/build
dist/
*.code-workspace
Expand Down
26 changes: 26 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,29 @@
Unreleased

Behaviour change

- `Graph.plot()` and `Graph.highlight_path()` now default to `block=None`
instead of `False`. They no longer call `plt.show()` unless `block` is
specified, allowing notebooks and other environments to manage display.
Scripts and plain IPython sessions without `%matplotlib` or `plt.ion()`
that relied on `g.plot()` opening a window now need an explicit
`plt.show()` after drawing, or `block=False` for the previous behaviour.
`block=True` still waits for the window to close.

Performance

- `closest()` and `near()` no longer make a Python-level pass over the vertices
when there is no k-d tree. The graph keeps the coordinates as a matrix, built
on first use and appended to by `add_vertex`, and applies the built-in metrics
to all rows at once. A query on a 1,000-vertex graph takes 12 microseconds
rather than 730, and stays that fast while vertices are being added, which is
what the Robotics Toolbox's `LatticePlanner` and `RRTPlanner` do (a lattice of
1,292 vertices is planned in 0.06 s rather than 1.07 s). Results are the
same. The matrix is a copy of the coordinates, so changing one in place,
`vertex.coord[0] = x`, is not seen by `closest()`, as was already so with
`build_kdtree()`; assigning `vertex.coord` is. A metric of your own is still
applied to each vertex in turn.

1.0.0

First 1.0 release: six years of production use since the first commit in 2020
Expand Down
6 changes: 4 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -60,6 +60,7 @@ This needs Python 3.9 or later. The dependencies, NumPy, Matplotlib and Spatial

```python
from pgraph import UGraph
import matplotlib.pyplot as plt
import json

# load the places and routes
Expand All @@ -75,8 +76,9 @@ for route in data['routes']:

# plan a path from Hughenden to Brisbane
p, length, _ = g.path_Astar('Hughenden', 'Brisbane')
g.plot(block=False) # plot it
g.highlight_path(p) # overlay the path
g.plot() # create the graph without displaying it yet
g.highlight_path(p) # overlay the path on the same axes
plt.show() # show the finished figure in a script
```

The data file and the complete example are in the notebook [`examples/roads.ipynb`](https://github.com/petercorke/pgraph-python/blob/main/examples/roads.ipynb).
Expand Down
18 changes: 17 additions & 1 deletion docs/llms_intro.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,11 @@
pgraph is a pure-Python package of graph classes: directed and undirected graphs of vertices connected by edges, with edge costs and path planning (breadth-first, uniform-cost and A*). Vertices can be *embedded*, given a coordinate in a space of any dimension; edge costs then come from a distance metric (L2, L1, SE2 or your own), and the graph can be queried spatially, plotted and exported. Self-loops and parallel edges are allowed. It requires Python 3.9 or later and depends on NumPy, Matplotlib and spatialmath-python. Install with `pip install pgraph-python`; import it as `pgraph`.

## When to use it

Reach for pgraph when a program needs a **small, explicit graph with path planning**: vertices with optional coordinates, directed or undirected edges with costs, and breadth-first, uniform-cost or A* search, plus nearest-vertex queries, plotting and export. It suits roadmaps, grid and lattice planners, pose graphs and teaching examples where you want the vertex and edge objects themselves, not just an adjacency structure. `import pgraph` loads only NumPy.

It is not a large-scale graph analytics package (use `networkx` for centrality, community detection or hundreds of algorithms; `igraph` or `graph-tool` for very large graphs), and it has no weighted-matching or flow algorithms.

## Quick start

```python
Expand All @@ -18,6 +24,16 @@ g.plot()
g.highlight_path(path)
```

## Recipes

- **Shortest path between two named places**: build a `UGraph`, `add_vertex` for each place with its coordinate and `name=`, `add_edge` between neighbours, then `path, length, _ = g.path_Astar("start", "goal")`.
- **Plan on a grid**: add one vertex per cell and an edge to each neighbour, with `cost=` if the cells differ; `path_BFS` gives the fewest steps, `path_Astar` the cheapest.
- **Find the vertex nearest a point**: `v, dist = g.closest(point)`; `g.near(point, radius)` for all within a radius.
- **Check whether two places are connected**: `g.samecomponent(v1, v2)`, or `g.nc` for the number of components.
- **Get the adjacency or Laplacian matrix**: `g.adjacency()`, `g.laplacian()`, as NumPy arrays.
- **Draw the graph and the route**: `g.plot()`, then `g.highlight_path(path)`.
- **Export for GraphViz or Mermaid**: `g.export("graph.dot")` or `g.export("graph.mmd")`.

## Key points

- **Classes.** `UGraph` (undirected) and `DGraph` (directed) share the base class `Graph`, which is concrete: `Graph(directed=True)` is a `DGraph`. There is one `Vertex` class for both and one `Edge` class. `UVertex` and `DVertex` are deprecated aliases of `Vertex`. Constructor arguments are keyword-only: `UGraph(dim=2, metric="L2", heuristic=None, vertex_class=None, edge_class=None, verbose=False)`; `UGraph(2)` is a `TypeError`.
Expand All @@ -28,7 +44,7 @@ g.highlight_path(path)
- **Metrics.** `"L2"` (default), `"L1"`, `"SE2"` for `(x, y, theta)` poses, `SE2Metric(weight)` to weight the angle, or a function of one difference vector. A* uses `heuristic` (default: the metric), which must be in the same units as the edge costs and must not exceed the true cost to go, or the path is not the shortest.
- **Spatial queries** on an embedded graph: `closest(point)` returns `(vertex, distance)`, `near(point, radius)`, `within(box)` with `box` a 2 x n array of lower and upper corner, `coordinates()` the `(dim, n)` matrix of coordinates, and `subgraph(vertices)`, which takes vertices, names or a boolean mask and returns a new graph. `build_kdtree()` is an optional index (it needs scipy) that `closest` and `near` then use.
- **Components and matrices.** `g.component(c)` is the vertices in component number `c`, `v.label` is the component of a vertex, `g.samecomponent(v1, v2)`. `adjacency()`, `incidence()`, `laplacian()`, `degree()` and `connectivity()` return dense NumPy arrays.
- **Output.** `g.plot()` (arrowheads for a directed graph, arcs for parallel edges, circles for loops), `highlight_path(path)`, and `g.export(file)` for GraphViz dot, Mermaid, GraphML, ELK JSON or an image (images need the GraphViz executables).
- **Output.** `g.plot()` (arrowheads for a directed graph, arcs for parallel edges, circles for loops), `highlight_path(path)`, and `g.export(file)` for GraphViz dot, Mermaid, GraphML, ELK JSON or an image (images need the GraphViz executables). Both methods default to `block=None`, leaving figure display to the environment. In scripts, use `plt.show()` after composing a figure, or `block=False` for the previous nonblocking show; `block=True` blocks until closed.
- **Subclassing.** `class Foo(Vertex)` and `UGraph(vertex_class=Foo, edge_class=Bar)` make the graph build them; a subclass `__init__` must pass `coord` and `name` (vertices) or `v1, v2, cost, data` (edges) to its parent.
- **Copying.** `g.copy()` and `pickle` work for a whole graph; a vertex or edge cannot be copied or pickled on its own, and a graph whose metric is a `lambda` cannot be pickled.

Expand Down
3 changes: 3 additions & 0 deletions docs/source/intro.rst
Original file line number Diff line number Diff line change
Expand Up @@ -152,6 +152,9 @@ The graph can be plotted by

>>> g.plot()

In a regular Python script, call ``plt.show()`` after drawing to display the
figure. Sphinx's ``plot`` directive and interactive notebooks handle display.

.. plot::

>>> import pgraph
Expand Down
5 changes: 1 addition & 4 deletions examples/create_json.py
Original file line number Diff line number Diff line change
Expand Up @@ -15,10 +15,7 @@
del info['y']
del info['dbne']
del info['utmzone']
try:
del info['dgoal']
except:
pass
info.pop('dgoal', None) # not every place has one
info['utm'] = [info['utm'][0] / 1000, info['utm'][1] / 1000]

routes = []
Expand Down
62 changes: 31 additions & 31 deletions examples/roads.ipynb
Original file line number Diff line number Diff line change
Expand Up @@ -187,35 +187,35 @@
"name": "stdout",
"output_type": "stream",
"text": [
"Edge{[Camooweal] -- [Mount Isa], cost=188}\n",
"Edge{[Mount Isa] -- [Cloncurry], cost=118}\n",
"Edge{[Cloncurry] -- [Hughenden], cost=401}\n",
"Edge{[Cloncurry] -- [Winton], cost=350}\n",
"Edge{[Hughenden] -- [Charters Towers], cost=248}\n",
"Edge{[Charters Towers] -- [Townsville], cost=135}\n",
"Edge{[Townsville] -- [Mackay], cost=388}\n",
"Edge{[Mackay] -- [Rockhampton], cost=334}\n",
"Edge{[Mackay] -- [Emerald], cost=384}\n",
"Edge{[Rockhampton] -- [Brisbane], cost=682}\n",
"Edge{[Rockhampton] -- [Emerald], cost=270}\n",
"Edge{[Brisbane] -- [Roma], cost=482}\n",
"Edge{[Roma] -- [Charleville], cost=266}\n",
"Edge{[Charleville] -- [Blackall], cost=305}\n",
"Edge{[Blackall] -- [Barcaldine], cost=106}\n",
"Edge{[Blackall] -- [Windorah], cost=530}\n",
"Edge{[Barcaldine] -- [Emerald], cost=307}\n",
"Edge{[Barcaldine] -- [Hughenden], cost=500}\n",
"Edge{[Barcaldine] -- [Longreach], cost=106}\n",
"Edge{[Longreach] -- [Windorah], cost=311}\n",
"Edge{[Longreach] -- [Winton], cost=180}\n",
"Edge{[Winton] -- [Hughenden], cost=216}\n",
"Edge{[Winton] -- [Boulia], cost=363}\n",
"Edge{[Winton] -- [Windorah], cost=487}\n",
"Edge{[Boulia] -- [Mount Isa], cost=304}\n",
"Edge{[Boulia] -- [Bedourie], cost=194}\n",
"Edge{[Bedourie] -- [Birdsville], cost=193}\n",
"Edge{[Birdsville] -- [Windorah], cost=380}\n",
"Edge{[Bedourie] -- [Windorah], cost=411}\n"
"Edge{[Camooweal] ↔ [Mount Isa], cost=188}\n",
"Edge{[Mount Isa] ↔ [Cloncurry], cost=118}\n",
"Edge{[Cloncurry] ↔ [Hughenden], cost=401}\n",
"Edge{[Cloncurry] ↔ [Winton], cost=350}\n",
"Edge{[Hughenden] ↔ [Charters Towers], cost=248}\n",
"Edge{[Charters Towers] ↔ [Townsville], cost=135}\n",
"Edge{[Townsville] ↔ [Mackay], cost=388}\n",
"Edge{[Mackay] ↔ [Rockhampton], cost=334}\n",
"Edge{[Mackay] ↔ [Emerald], cost=384}\n",
"Edge{[Rockhampton] ↔ [Brisbane], cost=682}\n",
"Edge{[Rockhampton] ↔ [Emerald], cost=270}\n",
"Edge{[Brisbane] ↔ [Roma], cost=482}\n",
"Edge{[Roma] ↔ [Charleville], cost=266}\n",
"Edge{[Charleville] ↔ [Blackall], cost=305}\n",
"Edge{[Blackall] ↔ [Barcaldine], cost=106}\n",
"Edge{[Blackall] ↔ [Windorah], cost=530}\n",
"Edge{[Barcaldine] ↔ [Emerald], cost=307}\n",
"Edge{[Barcaldine] ↔ [Hughenden], cost=500}\n",
"Edge{[Barcaldine] ↔ [Longreach], cost=106}\n",
"Edge{[Longreach] ↔ [Windorah], cost=311}\n",
"Edge{[Longreach] ↔ [Winton], cost=180}\n",
"Edge{[Winton] ↔ [Hughenden], cost=216}\n",
"Edge{[Winton] ↔ [Boulia], cost=363}\n",
"Edge{[Winton] ↔ [Windorah], cost=487}\n",
"Edge{[Boulia] ↔ [Mount Isa], cost=304}\n",
"Edge{[Boulia] ↔ [Bedourie], cost=194}\n",
"Edge{[Bedourie] ↔ [Birdsville], cost=193}\n",
"Edge{[Birdsville] ↔ [Windorah], cost=380}\n",
"Edge{[Bedourie] ↔ [Windorah], cost=411}\n"
]
}
],
Expand Down Expand Up @@ -406,8 +406,8 @@
}
],
"source": [
"g.plot(block=None) # block=None: show it once, with the path\n",
"g.highlight_path(p, alpha=0.5, scale=2, block=None)"
"g.plot() # draw; the notebook displays the completed figure\n",
"g.highlight_path(p, alpha=0.5, scale=2)"
]
},
{
Expand Down
2 changes: 2 additions & 0 deletions examples/roads.py
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
import json
from pgraph import UGraph, DGraph
import matplotlib.pyplot as plt

# load the JSON file
with open('queensland.json', 'r') as f:
Expand Down Expand Up @@ -32,6 +33,7 @@
# plot the graph, and overlay the path
g.plot()
g.highlight_path(p, alpha=0.5, scale=2)
plt.show() # show the completed figure in a script

# turn the vertex parent information into a tree, it's a dict that maps a
# vertex to its parent.
Expand Down
105 changes: 0 additions & 105 deletions posegraph.py

This file was deleted.

1 change: 1 addition & 0 deletions pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,7 @@ dependencies = ["spatialmath-python", "numpy>=2.0", "matplotlib"]
"Homepage" = "https://github.com/petercorke/pgraph-python"
"Bug Tracker" = "https://github.com/petercorke/pgraph-python/issues"
"Documentation" = "https://petercorke.github.io/pgraph-python"
"llms.txt" = "https://petercorke.github.io/pgraph-python/llms.txt"
"GitHub Source" = "https://github.com/petercorke/pgraph-python"
"Changelog" = "https://github.com/petercorke/pgraph-python/blob/main/CHANGELOG.md"
"Coverage" = "https://codecov.io/gh/petercorke/pgraph-python"
Expand Down
Loading
Loading