pysgn.utils

sample_points(n: int, *, bbox: Sequence[float] | None = None, polygon: Polygon | MultiPolygon | None = None, sampler: Callable[[Generator, int], ndarray] | None = None, random_state: int | None = None, crs: Any | None = None, max_attempts: int = 1000000) → GeoDataFrame

Sample point geometries within a spatial domain.

Returns a geometry-only GeoDataFrame with exactly n point geometries in the geometry column.

Domain definition:

• bbox only: sample in (xmin, ymin, xmax, ymax) bounds.

• polygon only: sample in polygon area.

• both: sample in polygon.intersection(bbox_polygon).

• at least one of bbox or polygon must be provided.

Sampling:

• sampler is None: uniform candidate generation over the final domain.

• sampler is callable: user-defined candidate generation with sampler(rng, k) -> array-like of shape (k, 2), followed by rejection against the final domain.

CRS handling:

• CRS is set only from explicit crs input with pyproj.CRS.from_user_input.

Args:

n: Number of points to generate; must be > 0. bbox: Bounding box sequence (xmin, ymin, xmax, ymax). polygon: Domain polygon geometry (Polygon or MultiPolygon only). sampler: Optional callable producing candidate coordinates. random_state: Random seed for deterministic output. crs: Optional CRS user input passed through

pyproj.CRS.from_user_input before assignment.

max_attempts: Maximum number of evaluated candidate points.

Returns:

A geometry-only geopandas.GeoDataFrame with n sampled points.

Raises:

ValueError: For invalid inputs (for example n <= 0, invalid

bbox/polygon, missing domain, invalid sampler, max_attempts <= 0, or non-positive final domain area).

RuntimeError: If sampling cannot produce n accepted points within

max_attempts evaluated candidate points.

graph_to_gdf(graph: Graph, *, nodes: bool = True, edges: bool = True) → tuple[GeoDataFrame | None, GeoDataFrame | None]

Convert a geospatial NetworkX graph into node and edge GeoDataFrames.

This function reconstructs node and edge GeoDataFrames from a graph that stores geospatial attributes. Node geometry is taken from the stored geometry attribute when available, otherwise it falls back to a Point created from the pos coordinates. The internal pos attribute is used for reconstruction but is omitted from exported node columns. Edge geometry uses a stored shapely geometry when present; otherwise it is built as a straight LineString between endpoint positions or centroids. CRS metadata is read from graph.graph["crs"] and applied to outputs when present.

Args:

graph: Graph containing geospatial node/edge attributes. nodes: Whether to build the node GeoDataFrame. edges: Whether to build the edge GeoDataFrame.

Returns:

A tuple of (nodes_gdf, edges_gdf) with None for any layer not requested.

Raises:

ValueError: If both nodes and edges are False. RuntimeError: If geometry cannot be reconstructed for a node or edge.