feat: coordinates(), build_kdtree(), subgraph mask, validate coordinates

coordinates() is the matrix of vertex coordinates, one column per vertex in
insertion order (NaN for a vertex with none), a view of a row-per-vertex array.
within() and near() are now computed on it with numpy, for the built-in
metrics, instead of vertex by vertex.

build_kdtree() builds an optional scipy cKDTree that closest() and near()
use for the built-in L1, L2 and SE2 (with its weight, using a periodic
dimension for the angle).  scipy is imported only inside the method and is
not added to pyproject.toml.  The index is dropped when a vertex is added or
removed or a coord is assigned (Vertex.__setattr__), so a stale index is never
used; a coordinate edited in place is documented as not seen.  It is not
copied or pickled.

subgraph() also takes a boolean mask of length n.  An integer vector is
refused, since it could be indices.

validate() now checks that coordinates are finite 1-D numeric vectors and,
when dim was not given, all of one length, and with embedded=True that every
vertex has one.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

Author: petercorke

docs/source/analysis.rst

@@ -50,18 +50,27 @@ Geometry and consistency
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
 For a graph whose vertices have coordinates,
-:meth:`~pgraph.PGraph.Graph.closest` finds the nearest vertex to a point,
-:meth:`~pgraph.PGraph.Graph.near` the vertices within a distance of a point and
-:meth:`~pgraph.PGraph.Graph.within` the vertices inside a box.  Passing the
-result of the last to :meth:`~pgraph.PGraph.Graph.subgraph` gives the part of
-the graph in a region, without the edges that cross its border.
+:meth:`~pgraph.PGraph.Graph.coordinates` is the matrix of them, one column per
+vertex.  :meth:`~pgraph.PGraph.Graph.closest` finds the nearest vertex to a
+point, :meth:`~pgraph.PGraph.Graph.near` the vertices within a distance of a
+point and :meth:`~pgraph.PGraph.Graph.within` the vertices inside a box.  Passing
+the result of the last to :meth:`~pgraph.PGraph.Graph.subgraph` gives the part of
+the graph in a region, without the edges that cross its border, and a boolean
+mask computed from the coordinates selects in the same way.
+
+These are a single pass over the vertices.  For a large graph that is queried
+often, :meth:`~pgraph.PGraph.Graph.build_kdtree` builds an index that
+:meth:`~pgraph.PGraph.Graph.closest` and :meth:`~pgraph.PGraph.Graph.near` then
+use, which needs scipy and is for the built-in metrics.
 
 .. autosummary::
    :nosignatures:
 
+   ~pgraph.PGraph.Graph.coordinates
    ~pgraph.PGraph.Graph.closest
    ~pgraph.PGraph.Graph.near
    ~pgraph.PGraph.Graph.within
+   ~pgraph.PGraph.Graph.build_kdtree
    ~pgraph.PGraph.Graph.subgraph
    ~pgraph.PGraph.Graph.validate
 
@@ -163,9 +172,11 @@ Details
 .. automethod:: pgraph.PGraph.Graph.samecomponent
 .. automethod:: pgraph.PGraph.Graph.connectivity
 .. automethod:: pgraph.PGraph.Graph.average_degree
+.. automethod:: pgraph.PGraph.Graph.coordinates
 .. automethod:: pgraph.PGraph.Graph.closest
 .. automethod:: pgraph.PGraph.Graph.near
 .. automethod:: pgraph.PGraph.Graph.within
+.. automethod:: pgraph.PGraph.Graph.build_kdtree
 .. automethod:: pgraph.PGraph.Graph.subgraph
 .. automethod:: pgraph.PGraph.Graph.validate