Skip to content

Commit 998bdfd

Browse files
committed
Merge upstream and document three-state plotting behaviour
2 parents a5c1744 + 5d64b2e commit 998bdfd

20 files changed

Lines changed: 755 additions & 263 deletions

‎.github/workflows/ci.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -76,7 +76,7 @@ jobs:
7676
pytest --cov=pgraph --cov-report=xml:coverage.xml
7777
coverage report
7878
- name: Upload coverage to Codecov
79-
uses: codecov/codecov-action@v7
79+
uses: codecov/codecov-action@303a32d7a59b442fa8d48b6a1cc6825c09c847a5 # v7.1.1
8080
with:
8181
files: ./coverage.xml
8282
verbose: true

‎.github/workflows/dependabot-auto-merge.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ jobs:
1313
steps:
1414
- name: Dependabot metadata
1515
id: metadata
16-
uses: dependabot/fetch-metadata@v3
16+
uses: dependabot/fetch-metadata@25dd0e34f4fe68f24cc83900b1fe3fe149efef98 # v3.1.0
1717
with:
1818
github-token: "${{ secrets.GITHUB_TOKEN }}"
1919

‎.github/workflows/publish.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -110,6 +110,6 @@ jobs:
110110
path: dist
111111

112112
# pinned to a commit, as this action can publish to PyPI; dependabot updates it
113-
- uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
113+
- uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3
114114
with:
115115
skip-existing: true

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
build/
12
docs/build
23
dist/
34
*.code-workspace

‎CHANGELOG.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,29 @@
1+
Unreleased
2+
3+
Behaviour change
4+
5+
- `Graph.plot()` and `Graph.highlight_path()` now default to `block=None`
6+
instead of `False`. They no longer call `plt.show()` unless `block` is
7+
specified, allowing notebooks and other environments to manage display.
8+
Scripts and plain IPython sessions without `%matplotlib` or `plt.ion()`
9+
that relied on `g.plot()` opening a window now need an explicit
10+
`plt.show()` after drawing, or `block=False` for the previous behaviour.
11+
`block=True` still waits for the window to close.
12+
13+
Performance
14+
15+
- `closest()` and `near()` no longer make a Python-level pass over the vertices
16+
when there is no k-d tree. The graph keeps the coordinates as a matrix, built
17+
on first use and appended to by `add_vertex`, and applies the built-in metrics
18+
to all rows at once. A query on a 1,000-vertex graph takes 12 microseconds
19+
rather than 730, and stays that fast while vertices are being added, which is
20+
what the Robotics Toolbox's `LatticePlanner` and `RRTPlanner` do (a lattice of
21+
1,292 vertices is planned in 0.06 s rather than 1.07 s). Results are the
22+
same. The matrix is a copy of the coordinates, so changing one in place,
23+
`vertex.coord[0] = x`, is not seen by `closest()`, as was already so with
24+
`build_kdtree()`; assigning `vertex.coord` is. A metric of your own is still
25+
applied to each vertex in turn.
26+
127
1.0.0
228

329
First 1.0 release: six years of production use since the first commit in 2020

‎docs/llms_intro.md‎

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,11 @@
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`.
22

3+
## When to use it
4+
5+
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.
6+
7+
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.
8+
39
## Quick start
410

511
```python
@@ -18,6 +24,16 @@ g.plot()
1824
g.highlight_path(path)
1925
```
2026

27+
## Recipes
28+
29+
- **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")`.
30+
- **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.
31+
- **Find the vertex nearest a point**: `v, dist = g.closest(point)`; `g.near(point, radius)` for all within a radius.
32+
- **Check whether two places are connected**: `g.samecomponent(v1, v2)`, or `g.nc` for the number of components.
33+
- **Get the adjacency or Laplacian matrix**: `g.adjacency()`, `g.laplacian()`, as NumPy arrays.
34+
- **Draw the graph and the route**: `g.plot()`, then `g.highlight_path(path)`.
35+
- **Export for GraphViz or Mermaid**: `g.export("graph.dot")` or `g.export("graph.mmd")`.
36+
2137
## Key points
2238

2339
- **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`.
@@ -28,7 +44,7 @@ g.highlight_path(path)
2844
- **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.
2945
- **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.
3046
- **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.
31-
- **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 plot methods default to `block=None`, which does not call `plt.show()` and lets the environment display the figure (useful for notebook overlays); `block=False` shows without waiting, and `block=True` waits in desktop GUI applications.
47+
- **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.
3248
- **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.
3349
- **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.
3450

‎docs/source/intro.rst‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -152,6 +152,9 @@ The graph can be plotted by
152152
153153
>>> g.plot()
154154
155+
In a regular Python script, call ``plt.show()`` after drawing to display the
156+
figure. Sphinx's ``plot`` directive and interactive notebooks handle display.
157+
155158
.. plot::
156159

157160
>>> import pgraph

‎examples/create_json.py‎

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -15,10 +15,7 @@
1515
del info['y']
1616
del info['dbne']
1717
del info['utmzone']
18-
try:
19-
del info['dgoal']
20-
except:
21-
pass
18+
info.pop('dgoal', None) # not every place has one
2219
info['utm'] = [info['utm'][0] / 1000, info['utm'][1] / 1000]
2320

2421
routes = []

‎examples/roads.ipynb‎

Lines changed: 31 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -187,35 +187,35 @@
187187
"name": "stdout",
188188
"output_type": "stream",
189189
"text": [
190-
"Edge{[Camooweal] -- [Mount Isa], cost=188}\n",
191-
"Edge{[Mount Isa] -- [Cloncurry], cost=118}\n",
192-
"Edge{[Cloncurry] -- [Hughenden], cost=401}\n",
193-
"Edge{[Cloncurry] -- [Winton], cost=350}\n",
194-
"Edge{[Hughenden] -- [Charters Towers], cost=248}\n",
195-
"Edge{[Charters Towers] -- [Townsville], cost=135}\n",
196-
"Edge{[Townsville] -- [Mackay], cost=388}\n",
197-
"Edge{[Mackay] -- [Rockhampton], cost=334}\n",
198-
"Edge{[Mackay] -- [Emerald], cost=384}\n",
199-
"Edge{[Rockhampton] -- [Brisbane], cost=682}\n",
200-
"Edge{[Rockhampton] -- [Emerald], cost=270}\n",
201-
"Edge{[Brisbane] -- [Roma], cost=482}\n",
202-
"Edge{[Roma] -- [Charleville], cost=266}\n",
203-
"Edge{[Charleville] -- [Blackall], cost=305}\n",
204-
"Edge{[Blackall] -- [Barcaldine], cost=106}\n",
205-
"Edge{[Blackall] -- [Windorah], cost=530}\n",
206-
"Edge{[Barcaldine] -- [Emerald], cost=307}\n",
207-
"Edge{[Barcaldine] -- [Hughenden], cost=500}\n",
208-
"Edge{[Barcaldine] -- [Longreach], cost=106}\n",
209-
"Edge{[Longreach] -- [Windorah], cost=311}\n",
210-
"Edge{[Longreach] -- [Winton], cost=180}\n",
211-
"Edge{[Winton] -- [Hughenden], cost=216}\n",
212-
"Edge{[Winton] -- [Boulia], cost=363}\n",
213-
"Edge{[Winton] -- [Windorah], cost=487}\n",
214-
"Edge{[Boulia] -- [Mount Isa], cost=304}\n",
215-
"Edge{[Boulia] -- [Bedourie], cost=194}\n",
216-
"Edge{[Bedourie] -- [Birdsville], cost=193}\n",
217-
"Edge{[Birdsville] -- [Windorah], cost=380}\n",
218-
"Edge{[Bedourie] -- [Windorah], cost=411}\n"
190+
"Edge{[Camooweal] ↔ [Mount Isa], cost=188}\n",
191+
"Edge{[Mount Isa] ↔ [Cloncurry], cost=118}\n",
192+
"Edge{[Cloncurry] ↔ [Hughenden], cost=401}\n",
193+
"Edge{[Cloncurry] ↔ [Winton], cost=350}\n",
194+
"Edge{[Hughenden] ↔ [Charters Towers], cost=248}\n",
195+
"Edge{[Charters Towers] ↔ [Townsville], cost=135}\n",
196+
"Edge{[Townsville] ↔ [Mackay], cost=388}\n",
197+
"Edge{[Mackay] ↔ [Rockhampton], cost=334}\n",
198+
"Edge{[Mackay] ↔ [Emerald], cost=384}\n",
199+
"Edge{[Rockhampton] ↔ [Brisbane], cost=682}\n",
200+
"Edge{[Rockhampton] ↔ [Emerald], cost=270}\n",
201+
"Edge{[Brisbane] ↔ [Roma], cost=482}\n",
202+
"Edge{[Roma] ↔ [Charleville], cost=266}\n",
203+
"Edge{[Charleville] ↔ [Blackall], cost=305}\n",
204+
"Edge{[Blackall] ↔ [Barcaldine], cost=106}\n",
205+
"Edge{[Blackall] ↔ [Windorah], cost=530}\n",
206+
"Edge{[Barcaldine] ↔ [Emerald], cost=307}\n",
207+
"Edge{[Barcaldine] ↔ [Hughenden], cost=500}\n",
208+
"Edge{[Barcaldine] ↔ [Longreach], cost=106}\n",
209+
"Edge{[Longreach] ↔ [Windorah], cost=311}\n",
210+
"Edge{[Longreach] ↔ [Winton], cost=180}\n",
211+
"Edge{[Winton] ↔ [Hughenden], cost=216}\n",
212+
"Edge{[Winton] ↔ [Boulia], cost=363}\n",
213+
"Edge{[Winton] ↔ [Windorah], cost=487}\n",
214+
"Edge{[Boulia] ↔ [Mount Isa], cost=304}\n",
215+
"Edge{[Boulia] ↔ [Bedourie], cost=194}\n",
216+
"Edge{[Bedourie] ↔ [Birdsville], cost=193}\n",
217+
"Edge{[Birdsville] ↔ [Windorah], cost=380}\n",
218+
"Edge{[Bedourie] ↔ [Windorah], cost=411}\n"
219219
]
220220
}
221221
],
@@ -406,8 +406,8 @@
406406
}
407407
],
408408
"source": [
409-
"g.plot(block=None) # block=None: show it once, with the path\n",
410-
"g.highlight_path(p, alpha=0.5, scale=2, block=None)"
409+
"g.plot() # draw; the notebook displays the completed figure\n",
410+
"g.highlight_path(p, alpha=0.5, scale=2)"
411411
]
412412
},
413413
{

‎examples/roads.py‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
import json
22
from pgraph import UGraph, DGraph
3+
import matplotlib.pyplot as plt
34

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

3638
# turn the vertex parent information into a tree, it's a dict that maps a
3739
# vertex to its parent.

0 commit comments

Comments
 (0)