pyudbm.binding.visual

Geometry foundation for visualization-oriented DBM / federation handling.

This module keeps matplotlib optional while exposing both the pure geometry layer and the first plotting-layer helpers built on top of it.

__all__

pyudbm.binding.visual.__all__ = ['BoundaryEdge3D', 'BoundaryLoop2D', 'BoundarySegment2D', 'EmptyGeometry', 'Face3D', 'Face2D', 'FaceGeometry3D', 'FederationGeometry3D', 'FederationGeometry2D', 'HalfSpace3D', 'HalfSpace2D', 'Interval1D', 'MultiInterval1D', 'Point3D', 'PointGeometry3D', 'Point2D', 'PointGeometry2D', 'PolyhedronGeometry3D', 'PolygonGeometry2D', 'PlotResult', 'SegmentGeometry3D', 'SegmentGeometry2D', 'extract_dbm_geometry', 'extract_federation_geometry', 'plot_dbm', 'plot_federation']

Built-in mutable sequence.

If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.

EmptyGeometry

class pyudbm.binding.visual.EmptyGeometry(dimension: int)[source]

Empty visualization geometry placeholder.

This is returned when clipping removes the whole region or when the source DBM / federation is empty in the requested render box.

Variables:

dimension (int) – User-visible geometry dimension.

Interval1D

class pyudbm.binding.visual.Interval1D(lower: float, upper: float, lower_closed: bool, upper_closed: bool, lower_clipped: bool = False, upper_clipped: bool = False)[source]

One clipped 1D interval with exact open/closed endpoint semantics.

The interval is always finite after clipping. Whether an endpoint comes from the original DBM or from the render-box clipping step is tracked separately.

Variables:

  • lower (float) – Lower endpoint after clipping.

  • upper (float) – Upper endpoint after clipping.

  • lower_closed (bool) – Whether the lower endpoint is included.

  • upper_closed (bool) – Whether the upper endpoint is included.

  • lower_clipped (bool) – Whether the lower endpoint was introduced by clipping.

  • upper_clipped (bool) – Whether the upper endpoint was introduced by clipping.

property is_point: bool

Return whether the interval collapses to one included point.

MultiInterval1D

class pyudbm.binding.visual.MultiInterval1D(intervals: Tuple[Interval1D, ...])[source]

Exact finite union of 1D intervals.

This is the 1D geometry form returned for federations.

Variables:

intervals (Tuple[Interval1D, ...]) – Normalized exact interval union in ascending order.

Point2D

class pyudbm.binding.visual.Point2D(x: float, y: float)[source]

One 2D point.

Variables:

  • x (float) – X coordinate.

  • y (float) – Y coordinate.

HalfSpace2D

class pyudbm.binding.visual.HalfSpace2D(a: float, b: float, c: float, is_strict: bool = False, is_clip: bool = False)[source]

One affine 2D half-space a*x + b*y <= c or a*x + b*y < c.

DBM constraints and clipping box edges are both converted to this common representation before polygon extraction.

Variables:

  • a (float) – Coefficient of x.

  • b (float) – Coefficient of y.

  • c (float) – Right-hand-side constant.

  • is_strict (bool) – Whether the inequality is strict.

  • is_clip (bool) – Whether this half-space comes from the render-box clipping boundary.

contains(point: Point2D, respect_strict: bool = True) → bool[source]

Return whether point satisfies this half-space.

contains_on_closure(point: Point2D) → bool[source]

Return whether point lies in the closure of this half-space.

evaluate(point: Point2D) → float[source]

Return a*x + b*y - c at point.

is_active(point: Point2D) → bool[source]

Return whether point lies on the boundary line of this half-space.

BoundarySegment2D

class pyudbm.binding.visual.BoundarySegment2D(start: Point2D, end: Point2D, is_closed: bool, is_clipped: bool)[source]

One directed 2D boundary segment.

Direction matters for loop tracing and for deciding outward arrow directions on unbounded clipped edges.

Variables:

  • start (Point2D) – Segment start point.

  • end (Point2D) – Segment end point.

  • is_closed (bool) – Whether this boundary segment is included in the represented set.

  • is_clipped (bool) – Whether this segment lies on the clipping box.

property length: float

Return Euclidean segment length.

property midpoint: Point2D

Return segment midpoint.

PolygonGeometry2D

class pyudbm.binding.visual.PolygonGeometry2D(vertices: Tuple[Point2D, ...], edges: Tuple[BoundarySegment2D, ...], halfspaces: Tuple[HalfSpace2D, ...])[source]

Convex 2D polygon extracted from one DBM inside the clip box.

Variables:

  • vertices (Tuple[Point2D, ...]) – Polygon vertices in boundary order.

  • edges (Tuple[BoundarySegment2D, ...]) – Directed boundary edges in boundary order.

  • halfspaces (Tuple[HalfSpace2D, ...]) – Active DBM and clip half-spaces used to define the polygon.

SegmentGeometry2D

class pyudbm.binding.visual.SegmentGeometry2D(segment: BoundarySegment2D, halfspaces: Tuple[HalfSpace2D, ...])[source]

Degenerate 2D line-segment geometry extracted from one DBM.

Variables:

  • segment (BoundarySegment2D) – Exact visible segment.

  • halfspaces (Tuple[HalfSpace2D, ...]) – Original half-space constraints used during extraction.

PointGeometry2D

class pyudbm.binding.visual.PointGeometry2D(point: Point2D, is_closed: bool, is_clipped: bool, halfspaces: Tuple[HalfSpace2D, ...])[source]

Degenerate 2D point geometry extracted from one DBM.

Variables:

  • point (Point2D) – Exact visible point.

  • is_closed (bool) – Whether the point is included.

  • is_clipped (bool) – Whether the point lies on the clipping box.

  • halfspaces (Tuple[HalfSpace2D, ...]) – Original half-space constraints used during extraction.

BoundaryLoop2D

class pyudbm.binding.visual.BoundaryLoop2D(segments: Tuple[BoundarySegment2D, ...], is_hole: bool)[source]

Closed 2D boundary loop of one federation component or hole.

Variables:

  • segments (Tuple[BoundarySegment2D, ...]) – Directed boundary segments that form the loop.

  • is_hole (bool) – Whether this loop bounds a hole instead of an outer face.

property signed_area: float

Return loop signed area.

property vertices: Tuple[Point2D, ...]

Return ordered loop vertices.

Face2D

class pyudbm.binding.visual.Face2D(outer: BoundaryLoop2D, holes: Tuple[BoundaryLoop2D, ...])[source]

One exact 2D face consisting of an outer loop and optional holes.

Variables:

FederationGeometry2D

class pyudbm.binding.visual.FederationGeometry2D(dbm_geometries: Tuple[PolygonGeometry2D | SegmentGeometry2D | PointGeometry2D, ...], boundary_segments: Tuple[BoundarySegment2D, ...], loops: Tuple[BoundaryLoop2D, ...], faces: Tuple[Face2D, ...], isolated_segments: Tuple[BoundarySegment2D, ...], isolated_points: Tuple[Point2D, ...], limits: Tuple[Tuple[float, float], Tuple[float, float]])[source]

Exact 2D geometry summary for one federation inside one render box.

It contains both the original per-DBM geometries and the exact union-level boundary decomposition.

Variables:

  • dbm_geometries (Tuple[Union[PolygonGeometry2D, SegmentGeometry2D, PointGeometry2D], ...]) – Exact clipped geometries of the individual DBMs.

  • boundary_segments (Tuple[BoundarySegment2D, ...]) – Exact union boundary segments after simplification and loop tracing.

  • loops (Tuple[BoundaryLoop2D, ...]) – Closed outer and hole loops reconstructed from the boundary graph.

  • faces (Tuple[Face2D, ...]) – Final union faces with hole assignment.

  • isolated_segments (Tuple[BoundarySegment2D, ...]) – Degenerate union segments not absorbed into 2D faces.

  • isolated_points (Tuple[Point2D, ...]) – Degenerate union points not absorbed into segments or faces.

  • limits (Tuple[Tuple[float, float], Tuple[float, float]]) – Effective 2D clip box used during extraction.

Point3D

class pyudbm.binding.visual.Point3D(x: float, y: float, z: float)[source]

One 3D point.

Variables:

  • x (float) – X coordinate.

  • y (float) – Y coordinate.

  • z (float) – Z coordinate.

HalfSpace3D

class pyudbm.binding.visual.HalfSpace3D(a: float, b: float, c: float, d: float, is_strict: bool = False, is_clip: bool = False)[source]

One affine 3D half-space a*x + b*y + c*z <= d or < d.

Variables:

  • a (float) – Coefficient of x.

  • b (float) – Coefficient of y.

  • c (float) – Coefficient of z.

  • d (float) – Right-hand-side constant.

  • is_strict (bool) – Whether the inequality is strict.

  • is_clip (bool) – Whether this half-space comes from the render-box clipping boundary.

contains(point: Point3D, respect_strict: bool = True) → bool[source]

Return whether point satisfies this half-space.

contains_on_closure(point: Point3D) → bool[source]

Return whether point lies in the closure of this half-space.

evaluate(point: Point3D) → float[source]

Return a*x + b*y + c*z - d at point.

is_active(point: Point3D) → bool[source]

Return whether point lies on the boundary plane of this half-space.

BoundaryEdge3D

class pyudbm.binding.visual.BoundaryEdge3D(start: Point3D, end: Point3D, is_closed: bool, is_clipped: bool)[source]

One directed 3D boundary edge.

Variables:

  • start (Point3D) – Edge start point.

  • end (Point3D) – Edge end point.

  • is_closed (bool) – Whether this edge is included in the represented set.

  • is_clipped (bool) – Whether this edge lies on the clipping box.

property length: float

Return Euclidean edge length.

property midpoint: Point3D

Return edge midpoint.

Face3D

class pyudbm.binding.visual.Face3D(vertices: Tuple[Point3D, ...], edges: Tuple[BoundaryEdge3D, ...], normal: Point3D, is_closed: bool, is_clipped: bool)[source]

One polygonal 3D face.

Variables:

  • vertices (Tuple[Point3D, ...]) – Ordered face vertices.

  • edges (Tuple[BoundaryEdge3D, ...]) – Directed face edges in boundary order.

  • normal (Point3D) – Outward face normal.

  • is_closed (bool) – Whether the face boundary plane is included.

  • is_clipped (bool) – Whether the face comes only from the clipping box.

FaceGeometry3D

class pyudbm.binding.visual.FaceGeometry3D(face: Face3D, halfspaces: Tuple[HalfSpace3D, ...])[source]

Degenerate 3D polygonal face geometry extracted from one DBM.

Variables:

  • face (Face3D) – Exact visible face.

  • halfspaces (Tuple[HalfSpace3D, ...]) – Original half-space constraints used during extraction.

SegmentGeometry3D

class pyudbm.binding.visual.SegmentGeometry3D(segment: BoundaryEdge3D, halfspaces: Tuple[HalfSpace3D, ...])[source]

Degenerate 3D line-segment geometry extracted from one DBM.

Variables:

  • segment (BoundaryEdge3D) – Exact visible segment.

  • halfspaces (Tuple[HalfSpace3D, ...]) – Original half-space constraints used during extraction.

PointGeometry3D

class pyudbm.binding.visual.PointGeometry3D(point: Point3D, is_closed: bool, is_clipped: bool, halfspaces: Tuple[HalfSpace3D, ...])[source]

Degenerate 3D point geometry extracted from one DBM.

Variables:

  • point (Point3D) – Exact visible point.

  • is_closed (bool) – Whether the point is included.

  • is_clipped (bool) – Whether the point lies on the clipping box.

  • halfspaces (Tuple[HalfSpace3D, ...]) – Original half-space constraints used during extraction.

PolyhedronGeometry3D

class pyudbm.binding.visual.PolyhedronGeometry3D(vertices: Tuple[Point3D, ...], edges: Tuple[BoundaryEdge3D, ...], faces: Tuple[Face3D, ...], halfspaces: Tuple[HalfSpace3D, ...])[source]

Convex 3D polyhedron extracted from one DBM inside the clip box.

Variables:

  • vertices (Tuple[Point3D, ...]) – Unique polyhedron vertices.

  • edges (Tuple[BoundaryEdge3D, ...]) – Unique visible boundary edges.

  • faces (Tuple[Face3D, ...]) – Polygonal boundary faces.

  • halfspaces (Tuple[HalfSpace3D, ...]) – Active DBM and clip half-spaces used to define the polyhedron.

FederationGeometry3D

class pyudbm.binding.visual.FederationGeometry3D(dbm_geometries: Tuple[PolyhedronGeometry3D | FaceGeometry3D | SegmentGeometry3D | PointGeometry3D, ...], limits: Tuple[Tuple[float, float], Tuple[float, float], Tuple[float, float]])[source]

Exact clipped 3D geometry summary for one federation.

The current 3D federation form keeps the exact clipped geometry of each constituent DBM instead of attempting a full 3D boolean-union boundary simplification.

Variables:

PlotResult

class pyudbm.binding.visual.PlotResult(ax: Any, fills: Tuple[Any, ...] = (), boundaries: Tuple[Any, ...] = (), markers: Tuple[Any, ...] = (), arrows: Tuple[Any, ...] = (), annotations: Tuple[Any, ...] = ())[source]

Matplotlib artist container returned by plot_dbm() and plot_federation().

The returned artists are grouped by role so callers can inspect, restyle, or remove them after plotting.

Variables:

  • ax (Any) – Axes that received the plotted artists.

  • fills (Tuple[Any, ...]) – Filled polygon/path artists.

  • boundaries (Tuple[Any, ...]) – Line artists for visible boundaries.

  • markers (Tuple[Any, ...]) – Point artists for endpoints or isolated points.

  • arrows (Tuple[Any, ...]) – Arrow artists indicating unbounded continuation.

  • annotations (Tuple[Any, ...]) – Text artists created by annotation support.

extract_dbm_geometry

pyudbm.binding.visual.extract_dbm_geometry(dbm: DBM, limits: Tuple[float, float] | Tuple[Tuple[float, float], Tuple[float, float]] | Tuple[Tuple[float, float], Tuple[float, float], Tuple[float, float]] | None = None) → EmptyGeometry | Interval1D | PolygonGeometry2D | SegmentGeometry2D | PointGeometry2D | PolyhedronGeometry3D | FaceGeometry3D | SegmentGeometry3D | PointGeometry3D[source]

Extract a pure-Python visualization geometry snapshot from one DBM.

This is the geometry-layer Phase 1 entry point. It intentionally performs no matplotlib import or artist creation.

For a 1D DBM this returns one clipped Interval1D or EmptyGeometry. For a 2D DBM it returns one exact clipped geometry object among PolygonGeometry2D, SegmentGeometry2D, PointGeometry2D, or EmptyGeometry.

Parameters:

  • dbm (DBM) – Source DBM to convert into visualization geometry.

  • limits (Optional[Union[Tuple[float, float], Tuple[Tuple[float, float], Tuple[float, float]], Tuple[Tuple[float, float], Tuple[float, float], Tuple[float, float]]]]) – Optional render limits. Use (xmin, xmax) for 1D, ((xmin, xmax), (ymin, ymax)) for 2D, and ((xmin, xmax), (ymin, ymax), (zmin, zmax)) for 3D. When omitted, limits are derived from the finite DBM bounds.

Returns:

Pure-Python exact geometry snapshot for the requested render box.

Return type:

Union[EmptyGeometry, Interval1D, PolygonGeometry2D, SegmentGeometry2D, PointGeometry2D, PolyhedronGeometry3D, FaceGeometry3D, SegmentGeometry3D, PointGeometry3D]

Raises:

  • TypeError – If dbm is not a DBM.

  • ValueError – If the DBM dimension is outside the supported range or if limits are malformed.

extract_federation_geometry

pyudbm.binding.visual.extract_federation_geometry(federation: Federation, limits: Tuple[float, float] | Tuple[Tuple[float, float], Tuple[float, float]] | Tuple[Tuple[float, float], Tuple[float, float], Tuple[float, float]] | None = None) → EmptyGeometry | MultiInterval1D | FederationGeometry2D | FederationGeometry3D[source]

Extract a pure-Python visualization geometry snapshot from one federation.

For 1D federations this returns the exact interval union. For 2D federations this returns the exact clipped polygon-union boundary for the polygonal DBM components.

Parameters:

  • federation (Federation) – Source federation to convert into visualization geometry.

  • limits (Optional[Union[Tuple[float, float], Tuple[Tuple[float, float], Tuple[float, float]], Tuple[Tuple[float, float], Tuple[float, float], Tuple[float, float]]]]) – Optional render limits. Use (xmin, xmax) for 1D, ((xmin, xmax), (ymin, ymax)) for 2D, and ((xmin, xmax), (ymin, ymax), (zmin, zmax)) for 3D. When omitted, limits are derived from the finite bounds of all DBMs in the federation.

Returns:

Exact pure-Python geometry summary for the requested render box.

Return type:

Union[EmptyGeometry, MultiInterval1D, FederationGeometry2D, FederationGeometry3D]

Raises:

  • TypeError – If federation is not a Federation.

  • ValueError – If the dimension is outside the supported range or if limits are malformed.

plot_dbm

pyudbm.binding.visual.plot_dbm(dbm: DBM, ax: Any | None = None, *, limits: Tuple[float, float] | Tuple[Tuple[float, float], Tuple[float, float]] | Tuple[Tuple[float, float], Tuple[float, float], Tuple[float, float]] | None = None, strict_epsilon: float | None = None, show_unbounded: bool = True, annotate: bool = False, annotate_text: str | None = None, baseline: float = 0.0, facecolor: Any | None = None, edgecolor: Any | None = None, alpha: float | None = None, linewidth: float | None = None, linestyle: Any | None = None, label: str | None = None, zorder: float | None = None) → PlotResult[source]

Plot one DBM with matplotlib.

Matplotlib remains an optional dependency. Importing this module does not require it, but calling plot_dbm() does.

The result is drawn on the provided axes or on a newly created axes when ax is omitted. The default legend label and, when enabled, the default annotation text are both derived from str(dbm).

Parameters:

  • dbm (DBM) – DBM to render.

  • ax (Optional[Any]) – Optional matplotlib axes. When omitted, a new axes is created.

  • limits (Optional[Union[Tuple[float, float], Tuple[Tuple[float, float], Tuple[float, float]], Tuple[Tuple[float, float], Tuple[float, float], Tuple[float, float]]]]) – Optional explicit render limits. Use (xmin, xmax) for 1D, ((xmin, xmax), (ymin, ymax)) for 2D, and ((xmin, xmax), (ymin, ymax), (zmin, zmax)) for 3D. When omitted, limits are inferred from the DBM bounds and merged with existing axes limits when plotting into a reused axes.

  • strict_epsilon (Optional[float]) – Optional positive epsilon used when shrinking fill interiors for strict inequalities.

  • show_unbounded (bool) – Whether clipped unbounded directions should be marked with arrows.

  • annotate (bool) – Whether to add one text annotation to the plotted geometry.

  • annotate_text (Optional[str]) – Optional annotation text. When omitted and annotate=True, str(dbm) is used. When provided while annotate is not True, plotting emits a warning and enables annotations automatically.

  • baseline (float) – Vertical baseline used by 1D plots.

  • facecolor (Optional[Any]) – Optional fill color for 2D and 3D regions. When both facecolor and edgecolor are omitted, the next matplotlib default cycle color is used.

  • edgecolor (Optional[Any]) – Optional boundary color. When omitted, it follows the fill color or the current axes color cycle.

  • alpha (Optional[float]) – Optional fill alpha for 2D and 3D regions.

  • linewidth (Optional[float]) – Optional boundary line width.

  • linestyle (Optional[Any]) – Optional default line style for closed boundaries.

  • label (Optional[str]) – Optional legend label. When omitted, str(dbm) is used.

  • zorder (Optional[float]) – Optional matplotlib z-order passed to created artists.

Returns:

Container of created matplotlib artists.

Return type:

PlotResult

Raises:

  • ImportError – If matplotlib is not installed.

  • NotImplementedError – If the DBM is outside the supported 1..3 user-clock range.

  • ValueError – If strict_epsilon is non-positive or if limits are malformed.

plot_federation

pyudbm.binding.visual.plot_federation(federation: Federation, ax: Any | None = None, *, limits: Tuple[float, float] | Tuple[Tuple[float, float], Tuple[float, float]] | Tuple[Tuple[float, float], Tuple[float, float], Tuple[float, float]] | None = None, strict_epsilon: float | None = None, show_unbounded: bool = True, annotate: bool = False, annotate_text: str | None = None, baseline: float = 0.0, color_mode: str = 'shared', facecolor: Any | None = None, edgecolor: Any | None = None, alpha: float | None = None, linewidth: float | None = None, linestyle: Any | None = None, label: str | None = None, zorder: float | None = None) → PlotResult[source]

Plot one federation with matplotlib.

For 1D federations this renders the exact interval union. For 2D federations this renders the exact clipped boundary extracted in the geometry layer. For 3D federations this renders the exact clipped geometry of each constituent DBM.

The default legend label and, when enabled, the default annotation text are both derived from str(federation).

Parameters:

  • federation (Federation) – Federation to render.

  • ax (Optional[Any]) – Optional matplotlib axes. When omitted, a new axes is created.

  • limits (Optional[Union[Tuple[float, float], Tuple[Tuple[float, float], Tuple[float, float]], Tuple[Tuple[float, float], Tuple[float, float], Tuple[float, float]]]]) – Optional explicit render limits. Use (xmin, xmax) for 1D, ((xmin, xmax), (ymin, ymax)) for 2D, and ((xmin, xmax), (ymin, ymax), (zmin, zmax)) for 3D. When omitted, limits are inferred from the federation bounds and merged with existing axes limits when plotting into a reused axes.

  • strict_epsilon (Optional[float]) – Optional positive epsilon used when shrinking fill interiors for strict inequalities.

  • show_unbounded (bool) – Whether clipped unbounded directions should be marked with arrows.

  • annotate (bool) – Whether to add text annotations to the plotted geometry.

  • annotate_text (Optional[str]) – Optional annotation text. When omitted and annotate=True, str(federation) is used. When provided while annotate is not True, plotting emits a warning and enables annotations automatically.

  • baseline (float) – Vertical baseline used by 1D plots.

  • color_mode (str) – "shared" to render federation pieces with one visual style, or "per_dbm" to show individual DBM pieces in distinct colors.

  • facecolor (Optional[Any]) – Optional fill color for 2D and 3D regions. When both facecolor and edgecolor are omitted, the next matplotlib default cycle color is used.

  • edgecolor (Optional[Any]) – Optional boundary color. When omitted, it follows the fill color or the current axes color cycle.

  • alpha (Optional[float]) – Optional fill alpha for 2D and 3D regions.

  • linewidth (Optional[float]) – Optional boundary line width.

  • linestyle (Optional[Any]) – Optional default line style for closed boundaries.

  • label (Optional[str]) – Optional legend label. When omitted, str(federation) is used.

  • zorder (Optional[float]) – Optional matplotlib z-order passed to created artists.

Returns:

Container of created matplotlib artists.

Return type:

PlotResult

Raises:

  • ImportError – If matplotlib is not installed.

  • NotImplementedError – If the federation is outside the supported 1..3 user-clock range.

  • ValueError – If strict_epsilon is non-positive, if color_mode is invalid, or if limits are malformed.