upxo.geoEntities.point2d module

2D Point geometric entity module for UPXO (Universal PolyXtal Operations).

This module provides two-dimensional point representations with support for lightweight (leanest) and feature-rich implementations. It includes geometric operations (distance, translation, rotation), type conversions (UPXO, Shapely, VTK, PyVista, GMSH), and point array generation methods.

Usage

from upxo.geoEntities.point2d import p2d_leanest from upxo.geoEntities.point2d import Point2d from upxo.geoEntities.point2d import Point2d as p2d

Classes

p2d_leanest

Minimal 2D point container (private coordinates, no features).

Point2d

Full-featured 2D point with attachable features and extensive geometric operations.

_coord_

Internal 3D coordinate storage used for z-level tracking.

Dependencies

Core (module-level):

numpy (np), math, copy.deepcopy, upxo._sup.dataTypeHandlers, upxo.geoEntities.bases, upxo.geoEntities.featmake, upxo._sup.validation_values, upxo.geoEntities.point3d

Optional (loaded on demand):

numpy.matlib — used in array_by_angles(). shapely.geometry — used in make_shape() and rettype='shapely' clustering. vtk — used in make_vtk_point(). pyvista — used in clustering with rettype='pyvista'. gmsh — used in clustering with rettype='gmsh'.

Notes

p2d_leanest is stable and should not be extended further; use Point2d for all new feature development.

Limitations

  • Pydantic validation is intentionally excluded to keep instantiation fast.

  • ABC inheritance was removed to eliminate per-object overhead.

See also

upxo.geoEntities.sline2d

2D line segments.

upxo.geoEntities.point3d

3D points.

Examples

Leanest (minimal) point:

>>> from upxo.geoEntities.point2d import p2d_leanest
>>> p = p2d_leanest(1.0, 2.0)
>>> p._x, p._y
(1.0, 2.0)

Full-featured point with distance:

>>> from upxo.geoEntities.point2d import Point2d as p2d
>>> p1, p2 = p2d(0, 0), p2d(3, 4)
>>> p1.distance(p2)
5.0

Generate a point array around a centroid:

>>> center = p2d(5, 5)
>>> points = center.array_by_clustering(n=10, r=2.0)
>>> len(points)
10

Rotate a point 90 degrees about the origin:

>>> p = p2d(1, 0)
>>> rotated = p.rotate_about_point(p2d(0, 0), 90, degree=True)

Convert to a Shapely Point:

>>> p = p2d(1, 1)
>>> sp = p.make_shape()
class upxo.geoEntities.point2d.p2d_leanest(x, y)[source]

Bases: object

Minimal 2D point container for lightweight, high-frequency operations.

Stores coordinates as private attributes (_x, _y) and provides compact distance and radius-membership checks with minimal overhead. Intended for inner-loop use where only core geometric predicates are required; use Point2d when richer features are needed.

Usage

from upxo.geoEntities.point2d import p2d_leanest

param x:

X-coordinate of the point.

type x:

float

param y:

Y-coordinate of the point.

type y:

float

_x

X-coordinate (private).

Type:

float

_y

Y-coordinate (private).

Type:

float

Limitations
-----------
- This class is frozen
Type:

do not add new methods or attributes.

- No feature dictionary, plane tracking, or type-conversion methods.
- No tolerance-aware equality; use ``Point2d`` for that.

Examples

>>> from upxo.geoEntities.point2d import p2d_leanest
>>> a = [p2d_leanest(1, 2), p2d_leanest(3, 4)]
>>> a[0]._x
1
squared_distance_to_coord(x, y)[source]

Compute squared Euclidean distance to a coordinate.

Parameters:

  • x (float) – Target coordinate.

  • y (float) – Target coordinate.

Returns:

Squared distance (self._x-x)^2 + (self._y-y)^2.

Return type:

float

is_coord_within_cor(x, y, cor=1e-08, on_cor_flag=True)[source]

Check if a coordinate is inside or on a circle centred at self.

Parameters:

  • x (float) – Coordinate to test.

  • y (float) – Coordinate to test.

  • cor (float, optional) – Circle radius.

  • on_cor_flag (bool, optional) – If True, include circle boundary (<= cor), else strict inside (< cor).

Returns:

True if coordinate satisfies circle-membership criterion.

Return type:

bool

Examples

from upxo.geoEntities.point2d import p2d_leanest
p2d_leanest(0, 0).is_coord_within_cor(0, 1, 1E-8)
is_p2dl_within_cor(point, cor=1e-08, on_cor_flag=True)[source]

Check if a lean-point is inside or on a circle centred at self.

Parameters:

  • point (p2d_leanest) – Lean point to test.

  • cor (float, optional) – Circle radius.

  • on_cor_flag (bool, optional) – If True, include circle boundary (<= cor), else strict inside (< cor).

Returns:

True if point satisfies circle-membership criterion.

Return type:

bool

Examples

from upxo.geoEntities.point2d import p2d_leanest
p2d_leanest(0, 0).is_p2dl_within_cor(p2d_leanest(0, 0), 1E-8)
is_p2d_within_cor(point, cor=1e-08, on_cor_flag=True)[source]

Check if a Point2d is inside or on a circle centred at self.

Parameters:

  • point (Point2d) – UPXO Point2d object to test.

  • cor (float, optional) – Circle radius.

  • on_cor_flag (bool, optional) – If True, include circle boundary (<= cor), else strict inside (< cor).

Returns:

True if point satisfies circle-membership criterion.

Return type:

bool

Examples

from upxo.geoEntities.point2d import p2d_leanest, Point2d
p2d_leanest(0, 0).is_p2d_within_cor(Point2d(0, 0), 1E-8)
class upxo.geoEntities.point2d.Point2d(x, y, plane='xy')[source]

Bases: object

Full-featured 2D point for UPXO geometry workflows.

The primary 2D point representation in UPXO. Supports rich geometric operations (distance, rotation, reflection, translation), equality and comparison utilities with tolerance, feature-dictionary attachment, and interoperability with Shapely, VTK, PyVista, and GMSH.

Usage

from upxo.geoEntities.point2d import Point2d from upxo.geoEntities.point2d import Point2d as p2d

param x:

First coordinate of the point (interpreted according to plane).

type x:

float

param y:

Second coordinate of the point (interpreted according to plane).

type y:

float

param plane:

Plane identifier — one of 'xy', 'yx', 'yz', 'zy', 'xz', 'zx'. Determines how x and y map to 3D axes in mixed-plane workflows. Default is 'xy'.

type plane:

str, optional

raises ValueError:

Raised by __eq__ / __ne__ when plist is empty or has an unrecognised point specification.

raises Limitations:

raises ———–:

raises - ABC inheritance was removed to eliminate per-object overhead; subclassing:

is possible but not recommended.

raises - Pydantic validation is excluded intentionally to keep instantiation fast.:

Notes

Refer to the Jupyter notebook demos in the repository for guided usage examples covering clustering, meshing, and crystal workflows.

Examples

>>> from upxo.geoEntities.point2d import Point2d
>>> Point2d(10, 12)
uxpo-p2d (10,12)

Intersection of two 2D lines:

>>> from upxo.geoEntities.point2d import Point2d
>>> from upxo.geoEntities.sline2d import Sline2d as sl2d
>>> la = sl2d.by_coord([0, 0], [1, 1])
>>> lb = sl2d.by_coord([0.1, 0.1], [1.8, 1.8])
>>> Point2d.from_intersection_two_lines(la, lb, tool='upxo')

Point at a parametric position along a line:

>>> from upxo.geoEntities.point2d import Point2d
>>> from upxo.geoEntities.sline2d import Sline2d
>>> Point2d.from_line_factor(Sline2d(-1, -1, 1, 1), 0.25)
ε = 1e-08
x
y
plane
eq(plist, *, use_tol=False)[source]

Named alias for __eq__, with optional tolerance support.

Parameters:

  • plist (Point2d, p2d_leanest, list, or tuple) – Point(s) to compare against self. See __eq__ for accepted specification types.

  • use_tol (bool, optional) – If True, apply tolerance-aware comparison. Default is False (exact comparison via __eq__).

Returns:

One boolean per comparison pair.

Return type:

list of bool

Warning

Tolerance-aware comparison (use_tol=True) is not yet implemented and will silently return None.

Examples

>>> from upxo.geoEntities.point2d import Point2d as p2d, p2d_leanest
>>> p2d(3, 4).eq(p2d_leanest(3, 4))
[True]
>>> p2d(3, 4).eq([p2d(1, 2), p2d(3, 4)])
[False, True]
eq_fast(plist, use_tol=False, point_spec=1)[source]

Fast equality check skipping type detection — caller must supply spec.

Unlike __eq__, no runtime type detection is performed; the caller declares the format of plist via point_spec. This avoids the overhead of find_spec_of_points() in tight loops.

Parameters:

  • plist (various) – Point(s) to compare. Format must match point_spec.

  • use_tol (bool, optional) – Reserved for future tolerance-aware comparison. Default False.

  • point_spec (int, optional) –

    Integer ID declaring the type/format of plist:

    ID

    Format

    1

    Point2d

    2

    [Point2d] or (Point2d, …)

    3

    p2d_leanest

    4

    [p2d_leanest]

    5

    [x, y] (flat, two numbers)

    6

    [[x, y]]

    7

    [[x1,y1], [x2,y2], …]

    8

    [[x1,x2,…], [y1,y2,…]]

    9–16

    Shapely/GMSH/VTK/PyVista variants

    Default is 1.

Returns:

Comparison result(s), or None for unimplemented spec IDs.

Return type:

list of bool or None

Warning

No input validation is performed. Passing a plist whose format does not match point_spec will raise an AttributeError or return a wrong answer silently.

Examples

>>> from upxo.geoEntities.point2d import Point2d as p2d, p2d_leanest
>>> p2d(3, 4).eq_fast(p2d(3, 4), point_spec=1)
[True]
>>> p2d(3, 4).eq_fast([p2d(1, 2), p2d(3, 4)], point_spec=2)
[False, True]
>>> p2d(3, 4).eq_fast([3, 4], point_spec=5)
[True]
ne(plist, *, use_tol=False)[source]

Named alias for __ne__, with optional tolerance support.

Parameters:

  • plist (Point2d, p2d_leanest, list, or tuple) – Point(s) to compare. See __eq__ for accepted formats.

  • use_tol (bool, optional) – If True, apply tolerance-aware comparison. Default False.

Returns:

Inequality results.

Return type:

list of bool

Warning

Tolerance-aware comparison (use_tol=True) is not yet implemented.

Examples

>>> from upxo.geoEntities.point2d import Point2d, p2d_leanest
>>> Point2d(3, 4).ne(p2d_leanest(3, 4))
[False]
add(d, update=True, throw=False, mydecatlen2NUM='b')[source]

Translate self by distance(s) d, in-place and/or returning new point(s).

Parameters:

  • d (float, list of float, list of list, or list of point objects) –

    Displacement to apply. Accepted forms:

    • scalar — added to both x and y.

    • [dx] — added to both x and y.

    • [dx, dy] — interpretation depends on mydecatlen2NUM.

    • [[dx, dy], …] — one new point per sub-list.

    • [[x1,x2,…], [y1,y2,…]] — column-wise displacement arrays.

    • [point_obj, …] — list of UPXO/Shapely/VTK/PyVista/GMSH 2D or 3D point objects.

  • update (bool, optional) – If True and d is a single scalar or (dx, dy) pair, update self.x and self.y in-place. Default True.

  • throw (bool, optional) – If True, return a new Point2d (or deepcopy of self when update=True). Default False.

  • mydecatlen2NUM ({'b', 'atxy', 'a', 'ta2sd'}, optional) –

    Disambiguation rule when d is a length-2 list of numbers:

    • 'b' / 'atxy' — treat as [dx, dy] (add to x and y separately). Default.

    • 'a' / 'ta2sd' — treat as two separate scalar displacements; returns two new points.

Returns:

When throw=True returns the translated point(s). When update=True, throw=False returns None (side-effect only).

Return type:

Point2d or list of Point2d or None

Examples

>>> from upxo.geoEntities.point2d import Point2d as p2d
>>> A = p2d(10, 12)
>>> A.add(5)
>>> A
uxpo-p2d (15,17)

Translate by separate dx/dy:

>>> A = p2d(10, 12)
>>> A.add([3, 4], mydecatlen2NUM='b')
>>> A
uxpo-p2d (13,16)

Return a new point without mutating self:

>>> A = p2d(10, 12)
>>> B = A.add(5, update=False, throw=True)
>>> B
uxpo-p2d (15,17)
mul(f=1.0, update=True, throw=False)[source]

Named alias for __mul__ with optional mutation and return control.

Parameters:

  • f (float or list of float) – Scaling factor. Scalar applies to both axes; an iterable of scalars applies each element as a separate scalar (one result per element).

  • update (bool, optional) – If True, scale self in-place. Default True.

  • throw (bool, optional) – If True, return the scaled point or a deepcopy of self. Default False.

Returns:

Returns scaled point(s) when throw=True, else None.

Return type:

Point2d or list of Point2d or None

Raises:

TypeError – If f is not a number or iterable.

Examples

>>> from upxo.geoEntities.point2d import Point2d as p2d
>>> point = p2d(-10, -12)
>>> point.mul(f=-2.5, update=False, throw=True)
uxpo-p2d (25.0,30.0)
classmethod from_intersection_two_lines(la, lb, tool='upxo', return_type='upxo')[source]

Construct a point at the intersection of two 2D lines.

The return value is a list so callers handle collinear cases (multiple points or infinitely many) uniformly.

Parameters:

  • la (Sline2d) – First 2D straight-line segment.

  • lb (Sline2d) – Second 2D straight-line segment.

  • tool ({'upxo', 'shapely'}, optional) – Backend to use for the intersection calculation. Default 'upxo'.

  • return_type (str, optional) – Format of returned point(s). Default 'upxo'.

Returns:

Intersection point(s). Empty list if lines do not intersect.

Return type:

list of Point2d

Notes

Collinear lines (same direction) return an empty list even when they overlap, as no unique intersection point exists.

Examples

>>> from upxo.geoEntities.sline2d import Sline2d
>>> from upxo.geoEntities.point2d import Point2d
>>> la = Sline2d.by_coord([0, 0], [1, 1])
>>> lb = Sline2d.by_coord([0, 1], [1, 0])
>>> Point2d.from_intersection_two_lines(la, lb, tool='upxo')

Collinear lines (no unique intersection):

>>> la = Sline2d.by_coord([0, 0], [1, 1])
>>> lb = Sline2d.by_coord([0.1, 0.1], [1.8, 1.8])
>>> Point2d.from_intersection_two_lines(la, lb, tool='upxo')
[]
classmethod from_line_factor(line, factor)[source]

Construct a point at a parametric position along a line.

Computes (x0 + factor*dx, y0 + factor*dy) where (x0, y0) is the line start and (dx, dy) is its direction vector.

Parameters:

  • line (Sline2d) – UPXO 2D straight-line segment.

  • factor (float) – Parametric factor. 0 → start point; 1 → end point; values outside [0, 1] extrapolate beyond the segment.

Returns:

Point at position start + factor * direction.

Return type:

Point2d

Examples

>>> from upxo.geoEntities.sline2d import Sline2d
>>> from upxo.geoEntities.point2d import Point2d
>>> Point2d.from_line_factor(Sline2d(-1, -1, 1, 1), 0.25)
>>> Point2d.from_line_factor(Sline2d(-1, -1, 1, 1), -0.25)
>>> Point2d.from_line_factor(Sline2d(-1, -1, 1, 1), 1.25)
classmethod from_intersection_lines_regions(lines, regions)[source]

Instantiate point(s) from intersections between lines and regions.

Parameters:

  • lines (iterable) – Collection of line-like entities.

  • regions (iterable) – Collection of region-like entities.

Notes

To be developed.

property coords

X and Y coordinates as a NumPy array.

Returns:

[x, y].

Return type:

numpy.ndarray, shape (2,)

Examples

>>> from upxo.geoEntities.point2d import Point2d
>>> A = Point2d(1.125, 0.456)
>>> A.coords
array([1.125, 0.456])
property shapely

Shapely Point representation of self.

Returns:

Point at (self.x, self.y).

Return type:

shapely.geometry.Point

Examples

>>> from upxo.geoEntities.point2d import Point2d
>>> A = Point2d(1.125, 0.456)
>>> A.shapely
<POINT (1.125 0.456)>
inside_line(line, consider_ends=True, consider_tol=False, tol=0.0)[source]

Test whether self lies on (within) a 2D line segment.

Parameters:

  • line (Sline2d) – UPXO 2D straight-line segment to test against.

  • consider_ends (bool, optional) – If True, points coinciding with the segment endpoints count as inside (<= comparison). If False, endpoints are excluded (< comparison). Default True.

  • consider_tol (bool, optional) – Reserved for tolerance-aware testing. Not yet implemented.

  • tol (float, optional) – Tolerance value for future use. Default 0.0.

Returns:

True if self lies on the segment, False otherwise.

Return type:

bool

Warning

Tolerance-aware testing (consider_tol=True) is not yet implemented and will have no effect.

Examples

>>> from upxo.geoEntities.point2d import Point2d
>>> from upxo.geoEntities.sline2d import Sline2d
>>> line = Sline2d.by_coord([0, 0], [1, 1])
>>> Point2d(0.5, 0.5).inside_line(line)
True
>>> Point2d(-0.5, -0.5).inside_line(line)
False
>>> Point2d(0, 0).inside_line(line, consider_ends=False)
False
squared_distance(plist=None)[source]

Compute squared Euclidean distances from self to one or more points.

Parameters:

plist (point spec or list of point specs) – Accepted formats match those of __eq__: single or list of Point2d, p2d_leanest, [x, y], [[x, y], …], or column arrays [[x1,…], [y1,…]].

Returns:

Squared distances (self.x - X)² + (self.y - Y)² for each target point.

Return type:

numpy.ndarray

Raises:

  • ValueError – If plist is empty.

  • Limitations –

  • ----------- –

  • - Only 2D point targets are supported; 3D, Shapely, GMSH, and VTK – targets are not yet implemented.

Examples

>>> from upxo.geoEntities.point2d import Point2d, p2d_leanest
>>> Point2d(0, 0).squared_distance(p2d_leanest(3, 4))
array([25.])
>>> Point2d(0, 0).squared_distance([Point2d(1, 2), Point2d(3, 4)])
array([ 5., 25.])
>>> Point2d(0, 0).squared_distance([[1, 2, -1, -3], [4, 5, 5, 6]])
array([17., 29., 26., 45.])
distance(plist=None)[source]

Compute Euclidean distances from self to one or more points.

Parameters:

plist (point spec or list of point specs) – Same accepted formats as squared_distance.

Returns:

  • numpy.ndarray – Euclidean distances sqrt((self.x-X)² + (self.y-Y)²).

  • Limitations

  • ———–

  • - Only 2D point targets are supported currently.

Examples

>>> from upxo.geoEntities.point2d import Point2d, p2d_leanest
>>> Point2d(0, 0).distance(p2d_leanest(3, 4))
array([5.])
>>> Point2d(0, 0).distance([Point2d(1, 2), Point2d(3, 4)])
array([2.23606798, 5.        ])
translate(*, vector=None, dist=None, update=False, throw=True, make3d=False, zloc=0)[source]

Translate self along vector by scalar distance dist.

The displacement applied is (vector / |vector|) * dist.

Parameters:

  • vector (list of float) – Direction vector; length 2 for 2D translation, length 3 when make3d=True and a Z-component is needed.

  • dist (float) – Distance to translate along vector.

  • update (bool, optional) – If True, update self’s coordinates in-place. Default False.

  • throw (bool, optional) – If True, return a point object. Default True.

  • make3d (bool, optional) – If True, return a Point3d instead of Point2d. Default False.

  • zloc (float, optional) – Z-coordinate for the returned Point3d when make3d=True and vector has length 2. Default 0.

Returns:

Translated point when throw=True; None otherwise.

Return type:

Point2d or Point3d or None

Examples

>>> from upxo.geoEntities.point2d import Point2d
>>> A = Point2d(0, 0)
>>> A.translate(vector=[1, 0], dist=5, update=True, throw=True)
uxpo-p2d (5.0,0.0)

Translate and return a 3D point:

>>> A = Point2d(0, 0)
>>> A.translate(vector=[-1, -1], dist=5, throw=True,
...             make3d=True, zloc=10)
static val_point_and_get_coord(point)[source]

Validate a single point specification and return its (x, y) coordinates.

static val_points_and_get_coords(points)[source]

Validate a collection of point specifications and return coordinate arrays (x, y).

translate_to(*, point=None, update=False, throw=True)[source]

Move self to an absolute target position.

Unlike translate, which applies a displacement, this method sets self’s coordinates to those of point directly.

Parameters:

  • point (Point2d, p2d_leanest, tuple, or list) – Target position. Any valid UPXO 2D point specification.

  • update (bool, optional) – If True, overwrite self.x and self.y. Default False.

  • throw (bool, optional) – If True, return the moved point. Default True.

Returns:

Moved point when throw=True, else None.

Return type:

Point2d or Point3d or None

Examples

>>> from upxo.geoEntities.point2d import Point2d as p2d
>>> A = p2d(0, 0)
>>> A.translate_to(point=p2d(1, 1), update=True, throw=True)
uxpo-p2d (1,1)

>>> A = p2d(0, 0)
>>> A.translate_to(point=(1, 1), update=True, throw=True)
uxpo-p2d (1,1)
rotate_about_point(point=None, angle=0, *, degree=True, update=False, throw=True, dec=8)[source]

Rotate self about an arbitrary pivot point by a given angle.

Parameters:

  • point (Point2d, p2d_leanest, tuple, or list) – Pivot point to rotate about.

  • angle (float) – Rotation angle. Interpreted as degrees when degree=True, radians otherwise.

  • degree (bool, optional) – If True, treat angle as degrees. Default True.

  • update (bool, optional) – If True, update self’s coordinates in-place. Default False.

  • throw (bool, optional) – If True, return the rotated point. Default True.

  • dec (int, optional) – Decimal places for rounding the output coordinates. Default 8.

Returns:

Rotated point when throw=True. A deepcopy of self is returned when update=True, throw=True; a new Point2d when update=False, throw=True.

Return type:

Point2d or None

Raises:

ValueError – If point is empty or angle is not a number.

Examples

>>> from upxo.geoEntities.point2d import Point2d as p2d
>>> p2d(1, 0).rotate_about_point(p2d(0, 0), 90,
...                              degree=True, update=True, throw=True)
uxpo-p2d (0.0,1.0)
>>> p2d(1, 0).rotate_about_point((0, 0), 45,
...                              degree=True, update=True, throw=True)
rotate_points(points=None, angles=0.0, *, degree=True, dec=8, return_type='p2d')[source]

Rotate one or more target points about self as the pivot.

Parameters:

  • points (Point2d, p2d_leanest, tuple, list, or column-array tuple) – Target point(s) to rotate. Accepted forms include single point objects, lists of point objects, (x, y) tuples, and column-array tuples ([x1, x2, …], [y1, y2, …]).

  • angles (float or array-like of float) – Rotation angle(s). Single scalar applied to all points; array must match the number of target points.

  • degree (bool, optional) – If True, treat angles as degrees. Default True.

  • dec (int, optional) – Decimal places for rounding output coordinates. Default 8.

  • return_type (str, optional) – Reserved for future return-format control. Default 'p2d'.

Returns:

Rotated coordinates [[x1, y1], [x2, y2], …].

Return type:

numpy.ndarray, shape (N, 2)

Raises:

ValueError – If points is empty or angles length mismatches points.

Examples

>>> from upxo.geoEntities.point2d import Point2d as p2d
>>> p2d(0, 0).rotate_points(p2d(1, 0), 45, degree=True)
>>> p2d(0, 0).rotate_points(([1, 2, 3], [0, 0, 0]), 45, degree=True)
attach_feature_(*, feature=None, feature_id=None)[source]

Attach a feature object to the point feature dictionary.

Parameters:

  • feature (object) – Feature instance to attach.

  • feature_id (hashable) – Key used to store/retrieve the feature within feature class bucket.

Raises:

  • ValueError – If feature or feature_id is empty.

  • KeyError – If feature_id already exists for the same feature class.

find_closest_points(plist=None, *, plane='xy', on_boundary=True)[source]

Return indices of the point(s) in plist closest to self.

Delegates to find_neigh_points_by_distance with r=0.

Parameters:

  • plist (list of Point2d, p2d_leanest, or coordinate arrays) – Collection of candidate points.

  • plane (str, optional) – Plane specifier. Default 'xy'.

  • on_boundary (bool, optional) – Passed through to find_neigh_points_by_distance. Default True.

Returns:

Indices of the closest point(s) in plist.

Return type:

numpy.ndarray of int

Examples

>>> from upxo.geoEntities.point2d import Point2d as p2d
>>> p2d(0, 0).find_closest_points([p2d(0, 0), p2d(0, 1), p2d(0, 0)])
array([0, 2])
>>> p2d(0, 0).find_closest_points([[1, 2], [2, 3], [0, -5],
...                                [1, 2], [1, 2]])
find_neigh_points_by_distance(plist=None, plane='xy', r=0, on_boundary=True)[source]

Return indices of points in plist within radius r of self.

Parameters:

  • plist (list or array-like) – Candidate points.

  • plane (str, optional) – Plane specifier. Default 'xy'.

  • r (float, optional) – Search radius. When r <= ε (≈ 0), returns the index/indices of the globally closest point(s). Default 0.

  • on_boundary (bool, optional) – If True, include points at exactly r. Default True.

Returns:

Indices of neighbouring points.

Return type:

numpy.ndarray of int

Raises:

TypeError – If r is not a number.

Examples

>>> from upxo.geoEntities.point2d import Point2d as p2d
>>> p2d(0, 0).find_neigh_points_by_distance([[1, 2], [10, 12], [0, 0]])
array([2])
find_neigh_points_by_count(plist=None, n=None, plane='xy')[source]

Return indices of the n nearest points in plist to self.

Parameters:

  • plist (list or array-like) – Candidate points.

  • n (int) – Number of nearest neighbours to return.

  • plane (str, optional) – Plane specifier. Default 'xy'.

Returns:

Indices of the n closest points (from numpy.where).

Return type:

tuple of numpy.ndarray

Raises:

  • TypeError – If n is not a non-zero integer.

  • ValueError – If n exceeds the length of plist.

Examples

>>> from upxo.geoEntities.point2d import Point2d as p2d
>>> p2d(0, 0).find_neigh_points_by_count(
...     [[1, 2], [10, 12], [0, -5], [0, 0]], n=2)
find_neigh_mulpoint_by_distance(*, mplist=None, plane='xy', r=0, tolf=-1)[source]

Find neighboring multi-points within a distance criterion.

Parameters:

  • mplist (iterable) – Collection of multi-point objects.

  • plane (str, optional) – Plane specifier. Defaults to xy.

  • r (float, optional) – Search radius.

  • tolf (float, optional) – Tolerance factor for membership decision.

Notes

To be developed.

find_neigh_edge_by_distance(*, elist=None, plane='xy', refloc='starting', r=0)[source]

Find neighboring edges using distance-based search.

Parameters:

  • elist (iterable) – Collection of edge objects.

  • plane (str, optional) – Plane specifier. Defaults to xy.

  • refloc (str, optional) – Edge reference location used for distance calculation.

  • r (float, optional) – Search radius.

Notes

To be developed.

find_neigh_muledge_by_distance(*, melist=None, plane='xy', refloc='starting', r=0)[source]

Find neighboring multi-edges using distance-based search.

Parameters:

  • melist (iterable) – Collection of multi-edge objects.

  • plane (str, optional) – Plane specifier. Defaults to xy.

  • refloc (str, optional) – Edge reference location used for distance calculation.

  • r (float, optional) – Search radius.

Notes

To be developed.

find_neigh_xtal_by_distance(*, xlist=None, plane='xy', refloc='starting', r=0)[source]

Find neighboring crystals using distance-based search.

Parameters:

  • xlist (iterable) – Collection of crystal objects.

  • plane (str, optional) – Plane specifier. Defaults to xy.

  • refloc (str, optional) – Crystal reference location used for distance calculation.

  • r (float, optional) – Search radius.

Notes

To be developed.

set_gmsh_props(prop_dict)[source]

Set Gmsh-related properties for point export/workflows.

Parameters:

prop_dict (dict) – Dictionary of Gmsh properties.

Notes

To be developed.

array_by_translation(ncopies=10, vector=[0, 0, 0], spacing='constant')[source]

Create translated copies of the point.

Parameters:

  • ncopies (int, optional) – Number of copies.

  • vector (iterable, optional) – Translation direction/magnitude specifier.

  • spacing (str, optional) – Spacing mode.

Notes

To be developed.

array_by_rotation(ncopies=10, vector=[0, 0, 0], spacing='constant')[source]

Create rotated copies of the point.

Parameters:

  • ncopies (int, optional) – Number of copies.

  • vector (iterable, optional) – Rotation axis/reference specifier.

  • spacing (str, optional) – Spacing mode.

Notes

To be developed.

array_on_arc(ncopies=10, r=1, angles=[0.0, 360.0], degree=True)[source]

Create point copies distributed on an arc.

Parameters:

  • ncopies (int, optional) – Number of copies.

  • r (float, optional) – Arc radius.

  • angles (iterable, optional) – Start and end angles.

  • degree (bool, optional) – If True, interpret angles in degrees.

Notes

To be developed.

array_by_clustering(n=10, r=1, distribution='urand', dmin=None, return_type='coord_list', zloc=0.0, gmsh_model_name='Model-1')[source]

Generate a random cluster of n points within radius r of self.

Self acts as the approximate centroid of the cluster. The larger n is, the closer the actual centroid converges to self.

Parameters:

  • n (int, optional) – Number of points to generate. Default 10.

  • r (float, optional) – Cluster radius. Default 1.

  • distribution ({'urand'}, optional) – Spatial distribution type. Currently only uniform random ('urand') is implemented. Default 'urand'.

  • dmin (float or None, optional) – Minimum inter-point distance constraint. Not yet implemented.

  • return_type (str, optional) –

    Format of the returned points. Accepted values:

    'coord_list'

    [[x0,…], [y0,…]] (default)

    'coords_2d'

    [[x0,y0], …]

    'upxo_2d'

    List of Point2d

    'upxo_2d_leanest'

    List of p2d_leanest

    'coord_list_3d'

    [[x0,…], [y0,…], [z0,…]]

    'coords_3d'

    [[x0,y0,z0], …]

    'shapely'

    List of shapely.geometry.Point

    'gmsh'

    List of GMSH point tags

    'pyvista'

    PyVista PolyData point cloud

    'mulpoint2d'

    UPXO mulpoint2d object

  • zloc (float, optional) – Z-coordinate for 3D or GMSH output. Default 0.0.

  • gmsh_model_name (str, optional) – GMSH model name created if GMSH is not yet initialised. Default 'Model-1'.

Returns:

  • varies – Format depends on return_type; see parameter description.

  • Limitations

  • ———–

    • Only distribution='urand' is implemented.

    • dmin constraint is not yet enforced.

Examples

>>> from upxo.geoEntities.point2d import Point2d as p2d
>>> p2d(0, 0).array_by_clustering(n=10, r=1)
>>> p2d(0, 0).array_by_clustering(n=10, r=1, return_type='coords_2d')
>>> p2d(0, 0).array_by_clustering(n=10, r=1, return_type='upxo_2d')
>>> p2d(0, 0).array_by_clustering(n=10, r=1, return_type='shapely')
lies_on_which_edge(*, elist=None, consider_ends=True)[source]

Return indices of edges on which the point lies.

Parameters:

  • elist (iterable) – Collection of edge objects.

  • consider_ends (bool, optional) – If True, consider edge endpoints as valid hits.

Notes

To be developed.

lies_in_which_xtal(*, xlist=None, cosider_boundary=True, consider_boundary_ends=True)[source]

Return indices of crystals containing this point.

Parameters:

  • xlist (iterable) – Collection of crystal objects.

  • cosider_boundary (bool, optional) – If True, include boundary checks.

  • consider_boundary_ends (bool, optional) – If True, include boundary-endpoint checks.

Notes

To be developed.

set_z(z=0)[source]

Attach a Z-coordinate to this 2D point via the feature dictionary.

Stores a _coord_ feature at key -1 under self.f.

Parameters:

z (float, optional) – Z-coordinate value to attach. Default 0.

Examples

>>> from upxo.geoEntities.point2d import Point2d as p2d
>>> A = p2d(10, 12)
>>> A.set_z(z=100)
>>> A.f['_coord_'][-1].z
100
make_vtk_point(z=0)[source]

Wrap this point as a VTK PolyData point.

Parameters:

z (float, optional) – Z-coordinate for the VTK point. If self.f does not already contain a _coord_ entry, set_z(z) is called first. Default 0.

Returns:

{'id': int, 'pd': vtkPolyData, 'help': str} where id is the inserted-point index and pd holds the vtkPolyData.

Return type:

dict

Examples

>>> from upxo.geoEntities.point2d import Point2d as p2d
>>> vtkobj = p2d(10, 12).make_vtk_point(z=100)
>>> x, y, z = vtkobj['pd'].GetPoint(vtkobj['id'])
make_shape()[source]

Create geometric shape representation of point.

Notes

To be developed.

f
upxo.geoEntities.point2d.all_isinstance(dtype, *args)[source]

Check whether all provided arguments are instances of a given type.

Parameters:

  • dtype (type) – Target Python/UPXO type to validate against.

  • *args (various) – Objects to test.

Returns:

True if every argument is an instance of dtype; None if no arguments are provided.

Return type:

bool or None

Examples

>>> from upxo.geoEntities.point2d import all_isinstance, p2d_leanest
>>> all_isinstance(p2d_leanest, p2d_leanest(0, 0), p2d_leanest(1, 1))
True