upxo.geoEntities.point3d module

3D point geometry entities for UPXO.

Provides the Point3d full-featured 3D point and the p3d_leanest lightweight variant for performance-critical use.

Classes

Point3d

Full-featured 3D point with coordinate operations, equality checks, distance calculations, and neighbour-finding methods.

p3d_leanest

Minimal 3D point for performance-critical collections. Intended for internal use only.

Usage

from upxo.geoEntities.point3d import Point3d as p3d

@author: Dr. Sunil Anandatheertha

class upxo.geoEntities.point3d.p3d_leanest(x, y, z)

Bases: object

Minimal 3D point class for performance-critical internal use.

Notes

Intentionally minimal — no methods beyond __init__ and __repr__. Further development should be avoided to keep memory overhead low.

Examples

from upxo.geoEntities.point3d import p3d_leanest

pts = [p3d_leanest(1, 2, 0), p3d_leanest(3, 4, 1)]

class upxo.geoEntities.point3d.Point3d(x, y, z=0.0)

Bases: UPXO_Point

3D point entity for UPXO.

Parameters:

• x (float) – x-coordinate.

• y (float) – y-coordinate.

• z (float, optional) – z-coordinate (default 0.0).

Notes

Inherits from UPXO_Point. Pydantic validation is intentionally avoided to minimise instantiation cost and memory overhead.

Examples

from upxo.geoEntities.point3d import Point3d as p3d

A, B, C = p3d(10, 12, 0), p3d(10, 12, 0), p3d(11, 12, 0)
print(A, B, C)

print(A == B, A != B, A == C, A != C)

A * 2
A + [10, 20, 30]

ε = 1e-08

x

y

z

eq(plist, use_tol=False, tolerance=None)

Overloaded equality check with optional tolerance.

Parameters:

• plist (point or list of points) – Points to compare against self.

• use_tol (bool, optional) – If True, apply tolerance (not yet implemented).

• tolerance (float, optional) – Tolerance threshold (not yet implemented).

Returns:

Element-wise equality results.

Return type:

list of bool

Examples

from upxo.geoEntities.point3d import Point3d as p3d, p3d_leanest

print(p3d(3, 4, 5).eq(p3d_leanest(3, 4, 5)))
print(p3d(3, 4, 5).eq([p3d_leanest(1, 4, 5), p3d_leanest(3, 4, 5)]))
print(p3d(3, 4, 5).eq(p3d(3, 4, 5)))
print(p3d(3, 4, 5).eq([p3d(1, 2, 5), p3d(3, 4, 5)]))
print(p3d(3, 4, 5).eq((p3d(1, 4, 5), p3d(3, 4, 5))))
print(p3d(3, 4, 5).eq([[1, 2, 5], [3, 4, 5], [5, 6, 5]]))
print(p3d(3, 4, 5).eq([[1, 3, 5], [2, 4, 6]]))
print(p3d(3, 4, 5).eq([[3, 4, 5]]))
print(p3d(3, 4, 5).eq([[3], [4], [5]]))

eq_fast(plist, use_tol=False, point_spec=1)

Fast equality check with explicit point-type specification.

Parameters:

• plist (point or array-like) – Points to compare.

• use_tol (bool, optional) – Tolerance flag (not yet implemented).

• point_spec (int, optional) –

  Integer code identifying the layout of plist:

  1 – Point3d; 2 – [Point3d]; 3 – p3d_leanest; 4 – [p3d_leanest]; 5 – [x, y, z]; 6 – [[x, y, z]]; 7 – [[x1,x2,...], [y1,y2,...], [z1,z2,...]] (row layout); 8 – [[x1,...], [y1,...], [z1,...]] (column layout).

Returns:

Element-wise equality results, or None for unrecognised spec.

Return type:

list of bool or None

Examples

from upxo.geoEntities.point3d import Point3d as p3d, p3d_leanest

print(p3d(3, 4, 5).eq_fast(p3d(3, 4, 5), point_spec=1))
print(p3d(3, 4, 5).eq_fast([p3d(1, 2, 5), p3d(3, 4, 5)], point_spec=2))
print(p3d(3, 4, 5).eq_fast((p3d(1, 4, 5), p3d(3, 4, 5)), point_spec=2))
print(p3d(3, 4, 5).eq_fast(p3d_leanest(3, 4, 5), point_spec=3))
print(p3d(3, 4, 5).eq_fast([p3d_leanest(1, 4, 5), p3d_leanest(3, 4, 5)], point_spec=4))
print(p3d(3, 4, 5).eq_fast([1, 2, 5], point_spec=5))
print(p3d(3, 4, 5).eq_fast([[1, 2, 5]], point_spec=6))
print(p3d(3, 4, 5).eq_fast([[1, 2, 5], [3, 4, 5], [5, 6, 5]], point_spec=7))
print(p3d(3, 4, 5).eq_fast([[3], [4], [5]], point_spec=8))

add(d, update=True, throw=False, mydecatlen2NUM='b')

Add scalar or vector d to self coordinates. Not yet implemented.

classmethod from_three_planes(plane1, plane2, plane3)

Find the point of intersection of three planes.

Parameters:

• plane1 (Plane) – First plane.

• plane2 (Plane) – Second plane.

• plane3 (Plane) – Third plane.

Returns:

Intersection point, or None if no unique solution exists (parallel or coincident planes).

Return type:

Point3d or None

Examples

from upxo.geoEntities.point3d import Point3d as p3d
from upxo.geoEntities.plane import Plane

plane1 = Plane(point=(0, 0, 1), normal=(1, 1, 1))
plane2 = Plane(point=(0, 0, 0), normal=(0, 1, 0))
plane3 = Plane(point=(0, 0, 0), normal=(0, 0, 1))
intersection_point = p3d.from_three_planes(plane1, plane2, plane3)
print(intersection_point)

property coords

Return [x, y] as a numpy array (2D projection of this 3D point).

squared_distance(plist=None, point_spec=-1)

Calculate squared distances between self and one or more points.

Parameters:

• plist (point or array-like) – Single point, list of points, or coordinate array. The expected layout depends on point_spec.

• point_spec (int, optional) –

  Integer code identifying the type of plist (default -1 for automatic detection):

  -1 – auto-detect via make_p3d();

  1 – Point3d; 2 – [Point3d]; 3 – p3d_leanest; 4 – [p3d_leanest]; 5 – (x, y, z) tuple; 6 – [(x, y, z)]; 7 – [[x,y,z], ...] row-major; 8 – [[x1,...], [y1,...], [z1,...]] column-major or (3, n) array.

Returns:

Squared Euclidean distance(s) from self to each input point.

Return type:

float or numpy.ndarray

Examples

from upxo.geoEntities.point3d import Point3d as p3d, p3d_leanest
import numpy as np

p3d(0, 0, 0).squared_distance(p3d(1, 1, 0), point_spec=-1)
p3d(0, 0, 0).squared_distance([[1,2,3,4],[1,2,3,4],[1,2,3,4]], point_spec=-1)
points = np.random.random((3, 100000))
p3d(0, 0, 0).squared_distance(points)
p3d(0, 0, 0).squared_distance(p3d(1, 1, 0), point_spec=1)
p3d(0, 0, 0).squared_distance([p3d(1, 1, 0)], point_spec=2)
p3d(0, 0, 0).squared_distance(p3d_leanest(1, 1, 0), point_spec=3)
p3d(0, 0, 0).squared_distance([p3d_leanest(1, 1, 0)], point_spec=4)
p3d(0, 0, 0).squared_distance((1, 1, 0), point_spec=5)
p3d(0, 0, 0).squared_distance([(1, 1, 0)], point_spec=6)
p3d(0, 0, 0).squared_distance([[1,2,3],[4,5,6],[7,8,9]], point_spec=7)
p3d(0, 0, 0).squared_distance([[1,2,3,4],[1,2,3,4],[1,2,3,4]], point_spec=8)
p3d(0, 0, 0).squared_distance(np.random.random((3, 100000)), point_spec=8)

distance(plist=None, point_spec=-1)

Calculate Euclidean distances between self and one or more points.

Parameters:

• plist (point or array-like) – See squared_distance() for accepted formats.

• point_spec (int, optional) – Point layout code passed through to squared_distance().

Returns:

Euclidean distance(s) from self to each input point.

Return type:

float or numpy.ndarray

Examples

from upxo.geoEntities.point3d import Point3d as p3d, p3d_leanest
import numpy as np

p3d(0, 0, 0).distance(p3d(1, 1, 0), point_spec=-1)
p3d(0, 0, 0).distance([[1,2,3,4],[1,2,3,4],[1,2,3,4]], point_spec=-1)
p3d(0, 0, 0).distance(p3d(1, 1, 0), point_spec=1)
p3d(0, 0, 0).distance([p3d(1, 1, 0)], point_spec=2)
p3d(0, 0, 0).distance(p3d_leanest(1, 1, 0), point_spec=3)
p3d(0, 0, 0).distance([p3d_leanest(1, 1, 0)], point_spec=4)
p3d(0, 0, 0).distance((1, 1, 0), point_spec=5)
p3d(0, 0, 0).distance([(1, 1, 0)], point_spec=6)
p3d(0, 0, 0).distance([[1,2,3],[4,5,6],[7,8,9]], point_spec=7)
p3d(0, 0, 0).distance([[1,2,3,4],[1,2,3,4],[1,2,3,4]], point_spec=8)
p3d(0, 0, 0).distance(np.random.random((3, 100000)), point_spec=8)

translate(*, vector=None, dist=None, update=False, throw=True)

Translate self along a vector by a given distance.

Parameters:

• vector (array-like) – Direction vector of translation.

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

• update (bool, optional) – If True, modify self in place.

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

Returns:

Translated point if throw is True, else None.

Return type:

Point3d or None

Examples

from upxo.geoEntities.point3d import Point3d as p3d

A = p3d(0, 0, 0)
A.translate(vector=[-1, -1, -1], dist=3.4641016151377544,
            update=True, throw=False)
print(A)

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

Translate self to the location of point.

static val_points_and_get_coords(points)

Docstring.

attach_feature(*, feature=None, feature_id=None)

Attach a feature object to self.f[feature_id].

find_neigh_point_by_distance(*, plist=None, plane='xy', r=0, on_boundary=True, threshold_perp_dist=0.0)

Things to do:

1. validations

2. consider plane in calculations. If plane is None, then all

   point locatyions within or withon r will be returned. If plane is specified differenyly, then return locations of those points which aactually satisfy both r and contained on or close to the plane. The closeneess sho9uld be determined by threshold_perp_dist, which is sthe threshold perpendicualr distance between a candidate point and yhe plane.

find_neigh_point_by_count(*, plist=None, n=None, plane='xy')

Find the n nearest points in plist by squared distance.

Parameters:

• plist (array-like) – Pool of candidate points.

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

• plane (str, optional) – Reserved for plane-filtered searches. Currently unused.

Returns:

Indices of the n nearest points in plist.

Return type:

tuple of numpy.ndarray

Examples

from upxo.geoEntities.point3d import Point3d as p3d

p3d(0, 0, 0).find_neigh_point_by_count(
    plist=[[1, 2, 0], [10, 12, 0], [0, -5, 0], [0, 0, 0]], n=2)

find_neigh_mulpoint_by_distance(*, mplist=None, plane='xy', r=0, tolf=-1)

Find neighbouring multi-point objects within radius r. Not yet implemented.

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

Find neighbouring edges within radius r. Not yet implemented.

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

Find neighbouring multi-edges within radius r. Not yet implemented.

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

Find neighbouring crystals within radius r. Not yet implemented.

set_gmsh_props(prop_dict)

Apply GMSH mesh properties from prop_dict to this point. Not yet implemented.

array_translation(*, ncopies=10, vector=[[0, 0, 0], [0, 0, 1]], spacing='constant')

Generate an array of translated copies along vector. Not yet implemented.

lies_on_which_line(*, llist=None, consider_ends=True)

Return which line(s) in llist this point lies on. Not yet implemented.

lies_in_which_xtal(*, xlist=None, cosider_boundary=True, consider_boundary_ends=True)

Return which crystal(s) in xlist contain this point. Not yet implemented.

make_vtk_point(z=0)

Create a VTK point dataset from self.

Parameters:

z (float, optional) – Unused; retained for API compatibility.

Returns:

Dictionary with keys 'id' (point ID), 'pd' (vtkPolyData), and 'help' (usage hint string).

Return type:

dict

Examples

from upxo.geoEntities.point3d import Point3d as p3d

A = p3d(10, 12, 100)
vtkobj = A.make_vtk_point()
x, y, z = vtkobj['pd'].GetPoint(vtkobj['id'])
print(x, y, z)

make_shape()

Create a geometric shape representation of this point. Not yet implemented.

pln

f