upxo.geoEntities.muledge2d module

2D multi-edge collection entity for UPXO.

Usage

from upxo.geoEntities.muledge2d import muledge2d

Classes

muledge2d : Ordered collection of connected 2D edges with spatial operations.

Notes

A muledge2d stores an ordered, optionally closed chain of edge2d objects, backed by a shared MPoint2d multi-point object for fast spatial queries.

class upxo.geoEntities.muledge2d.muledge2d(method='cpairs_list', ordered=True, closed=False, psense='ccw', esense='ccw', clist=[], cpairs_list=[], points=[], edges=None, edge_base='upxo', pindices=[], eindices=[], make_mp=True, make_emp=True, lean='ignore', plean='ignore', mplean='ignore', elean='ignore', melean='ignore')

Bases: object

Ordered collection of connected 2D edges with spatial and geometric operations.

Represents a chain of edge2d objects sharing endpoints. Supports multiple construction pathways (coordinate list, coordinate-pair list, point objects) and exposes properties such as lengths, slopes, centroid, and roughness over the full chain.

Usage

from upxo.geoEntities.muledge2d import muledge2d

Notes

Several mutation methods rebuild the internal point, edge, memory-id, and multi-point databases after editing the chain. These cached structures are part of the public state used by older UPXO geometry workflows.

ROUND_ZERO_DEC_PLACE = 10

EPS = 1e-12

dim

ordered

closed

psense

esense

lean

plean

mplean

elean

cpairs

ppairs

points

clist

pindices

pmids

pmid_pairs

edges

eindices

mpoint

empoints

dbbuild_plean()

Rebuild self.plean from the lean of each point in the chain.

Returns:

Updates self.plean in place.

Return type:

None

dbbuild_elean()

Rebuild self.elean from the lean of each edge in the chain.

Returns:

Updates self.elean in place.

Return type:

None

dbbuild_pmid()

Rebuild self.pmids from id() of each point in the chain.

Returns:

Updates self.pmids in place.

Return type:

None

dbbuild_pmid_pairs()

Rebuild self.pmid_pairs from id() of each point-pair.

Returns:

Updates self.pmid_pairs in place.

Return type:

None

dbbuild_points(method='ppairs', data=None)

Rebuild self.points from point-pair data.

Parameters:

• method (str, optional) – Rebuild strategy. Currently 'ppairs' rebuilds the ordered point deque from self.ppairs.

• data (object, optional) – Reserved for alternate rebuild inputs.

Returns:

Updates self.points in place.

Return type:

None

dbbuild_mpoint()

Rebuild self.mpoint as a mulpoint2d from all chain points.

Returns:

Updates self.mpoint in place.

Return type:

None

dbbuild_empoint()

Rebuild self.empoints as per-edge mulpoint2d objects.

Returns:

Updates self.empoints in place.

Return type:

None

dbbuild_edges()

Rebuild self.edges as edge2d objects from self.ppairs.

Returns:

Updates self.edges in place.

Return type:

None

edit_edge_add_point(eind, obj)

Adds point (obj) between pnta and pntb and make two edges Original edge gets edited, new one will be returned. returns the additional edge. If EDGE be the edge and OBJ be the point object being added, then the resulting edges will be:

edge 1: EDGE.pnta  --  OBJ
edge 2: OBJ  --  EDGE.pntb

Parameters:

• eind (int) – Specifies which edge to be edited

• obj (Point2d) – Specifies the UPXO point2d object to be inserted

Return type:

None.

property centroid

Return the UPXO centroid point.

Returns:

Centroid of the underlying multi-point object.

Return type:

Point2d

property centroids

Return centroids of constituent edges.

Returns:

Centroid point of each edge2d in the chain.

Return type:

list

property lengths

Return lengths of constituent edges.

Returns:

Length of each edge2d in the chain.

Return type:

list of float

property slopes

Return slopes of constituent edges.

Returns:

Slope of each edge2d in the chain.

Return type:

list of float

property length

Return total length of constituent edges.

Returns:

Sum of all edge lengths in the chain.

Return type:

float

property mean_length

Return mean length of constituent edges.

Returns:

Arithmetic mean of all edge lengths in the chain.

Return type:

float

property mean_slope

Return mean slope of constituent edges.

Returns:

Arithmetic mean of all edge slopes in the chain.

Return type:

float

property roughness

Roughness measure of the chain.

Raises:

NotImplementedError – Always raised because the roughness measure is not implemented.

property angles180

Orientation angles of each vertex coordinate in [−180°, 180°].

Returns:

Angles computed from the positive x-axis for each coordinate in self.clist, signed by the y-component.

Return type:

list of float

property angles

Orientation angles of each vertex coordinate in [0°, 360°].

Returns:

Angles in degrees measured counter-clockwise from the positive x-axis for each coordinate in self.clist.

Return type:

list of float

make_ring(saa=True, throw=False, close_index=0)

Close this multi-edge into a ring by connecting the last point to the first.

Parameters:

• saa (bool, optional) – Save-and-apply: modify self in place. Default True.

• throw (bool, optional) – Return a new closed object instead of modifying in place. Default False.

• close_index (int, optional) – Index of the point to close back to. Default 0.

Return type:

None

Notes

Closing updates: points, edges, cpairs, ppairs, empoints, pindices, pmids, pmid_pairs, and self.closed.

Examples

from upxo.geoEntities.muledge2d import muledge2d
cpairs_list = [[[1, 1], [-1, 1]], [[-1, 1], [-1, -1]],
               [[-1, -1], [1, -1]]]
me = muledge2d(method='cpairs_list', ordered=True, closed=False,
               cpairs_list=cpairs_list, lean='ignore')
me.make_ring()
me.is_ring()

is_ring(fast=True)

Return True if this multi-edge forms a closed ring.

Parameters:

fast (bool, optional) – When True (default), compare point memory ids (fast). When False, compare point coordinate equality.

Returns:

True if the first and last points coincide.

Return type:

bool

Notes

A ring requires: all edges share the same sense; edges are adjacent from pnta of edge 0 to pntb of edge −1; and pnta of edge 0 equals pntb of edge −1.

pop_point_by_index(n)

Delete the n-th point from the multi-edge chain.

Parameters:

n (int) – Index of the point to remove (within range(len(self.points))).

Return type:

None

Examples

from upxo.geoEntities.muledge2d import muledge2d
clist = [[0.0, 0.0], [0.5, 0.0], [1.0, 0.0],
         [1.5, 0.5], [1.0, 1.01], [2.0, 2.0], [2.5, 0.0]]
me = muledge2d(method='clist', ordered=True, closed=False,
               clist=clist, make_mp=True, lean='ignore')
me.pop_point_by_index(0)

pop_points_by_indices(n)

Delete multiple points from the multi-edge chain by index.

Parameters:

n (int or list of int) – Index or list of indices of points to remove.

Return type:

None

Examples

from upxo.geoEntities.muledge2d import muledge2d
clist = [[0.00, 0.00], [0.50, 0.00], [1.00, 0.00],
         [1.50, 0.50], [1.00, 1.01], [2.00, 2.00], [2.50, 0.00]]
me = muledge2d(method='clist', ordered=True, closed=False,
               clist=clist, make_mp=True, make_emp=True,
               lean='ignore', plean='ignore', mplean='ignore',
               elean='ignore', melean='ignore')
n = [0, 2, 4, 6]
me.pop_points_by_indices(n)

pop_point_by_coord(coord=None, tdist=0.1)

Delete point object at coord from the mul-edge object

Parameters:

coord (list, tuple, deque, or numpy.ndarray) – A single co-ordinate pair

Return type:

None.

Examples

from upxo.geoEntities.muledge2d import muledge2d
clist = [[0.00, 0.00], [0.50, 0.00], [1.00, 0.00],
         [1.50, 0.50], [1.00, 1.01], [2.00, 2.00], [2.50, 0.00]]
me = muledge2d(method='clist', ordered=True, closed=False,
               clist=clist, make_mp=True, make_emp=True,
               lean='ignore', plean='ignore', mplean='ignore',
               elean='ignore', melean='ignore')
me.pop_point_by_coord(coord=[0.1, 0.0], tdist=1.0)

insert_point_by_index(obj, index=None)

Insert one point into the multi-edge at the given index position.

Parameters:

• obj (Point2d or list of float) – Point to insert. A coordinate pair [x, y] is automatically promoted to a Point2d.

• index (int, optional) – Position in the point list where the new point will be inserted. Default is None.

Return type:

None

Examples

from upxo.geoEntities.muledge2d import muledge2d
from upxo.geoEntities.point2d import Point2d
clist = [[0, 0], [0.5, 0], [1, 0], [1.5, 0.5]]
me = muledge2d(method='clist', ordered=True, clist=clist, lean='ignore')
me.insert_point_by_index(Point2d(0, 5), index=1)

fine(level)

Subdivide all edges by inserting their centroids, level times.

Parameters:

level (int) – Number of subdivision passes. Must be in [0, 2].

Return type:

None

Examples

from upxo.geoEntities.muledge2d import muledge2d
me = muledge2d(method='clist', ordered=True,
               clist=[[0, 0], [1, 0], [2, 0]], lean='ignore')
me.fine(level=1)

insert_point(obj, index=None, insertion_check='edge')

Insert a single point into the multi-edge at the specified position.

Parameters:

• obj (Point2d) – The point to insert.

• index (int, optional) – Position at which to insert the point. Default is None.

• insertion_check (str, optional) – Strategy used to validate the insertion location. 'edge' checks containment on an existing edge; 'index' uses the raw index directly. Default is 'edge'.

Returns:

• None

• Limitations

• ———–

• - Implementation is incomplete; only the multi-point bookkeeping is – partially done. Edge rebuilding is a stub (pass).

• • insertion_check='edge' only works for non-intersecting edge chains.

Examples

from upxo.geoEntities.point2d import Point2d
from upxo.geoEntities.muledge2d import muledge2d
clist = [[0.0, 0.0], [0.5, 0.0], [1.0, 0.0], [1.5, 0.5]]
me = muledge2d(method='clist', ordered=True, closed=False,
               clist=clist, make_mp=True, make_emp=True,
               lean='ignore')
me.insert_point(Point2d(0.25, 0.0), index=1)

insert_coord_at(coord, indices=[0, 1])

Insert a raw coordinate into the chain at the given edge indices.

Parameters:

• coord (array-like) – Coordinate to insert into the multi-edge chain.

• indices (list of int, optional) – Edge or point indices that identify the insertion location. Default is [0, 1].

Raises:

NotImplementedError – Always raised because coordinate insertion is not implemented.

insert_point_bw(k=0.5)

Insert a point at fractional position k along each edge.

Parameters:

k (float, optional) – Fractional position along the edge, where 0 corresponds to the start point and 1 to the end point. Default is 0.5.

Raises:

NotImplementedError – Always raised because fractional insertion is not implemented.

move_nthpoint(n=0, xyincr=[0, 0], overlap_action='exit')

Translate the n-th point by a coordinate increment.

Parameters:

• n (int, optional) – Index of the point to move. Default 0.

• xyincr (list of float, optional) – Translation increment [dx, dy]. Default [0, 0].

• overlap_action (str, optional) – Behaviour when the new position coincides with an existing point. 'exit' rejects the move; 'remove_edge2' removes the resulting dangling edge. Default 'exit'.

Returns:

• None

• Limitations

• ———–

• • 'remove_edge2' branch is not yet fully implemented.

move_pointat(coord=[0, 0])

Move the point at coord to a new position.

Parameters:

coord (array-like, optional) – Coordinate of the point to be moved. Default is [0, 0].

Raises:

NotImplementedError – Always raised because coordinate-based point movement is not implemented.

explode(k, method='centroid')

Explode the chain outward from a reference location.

Parameters:

• k (float) – Scaling factor for outward movement.

• method (str, optional) – Reference definition for the explosion operation. Default is 'centroid'.

Raises:

NotImplementedError – Always raised because chain explosion is not implemented.

move()

Translate the entire multi-edge chain.

Raises:

NotImplementedError – Always raised because whole-chain translation is not implemented.

stretch()

Stretch the chain along an axis.

Raises:

NotImplementedError – Always raised because whole-chain stretching is not implemented.

plotme(i=None, j=None, show_coord=True)

Plot a slice of the edge chain using Matplotlib.

Parameters:

• i (int, optional) – Start index of the edge slice. Defaults to 0.

• j (int, optional) – End index (exclusive) of the edge slice. Defaults to len(self.edges).

• show_coord (bool, optional) – Annotate each node with its (x, y) coordinates. Default True.

plotmp()

Plot all multi-point nodes with coordinate annotations.

Returns:

Adds point markers and coordinate labels to the active Matplotlib axes.

Return type:

None