upxo.geoEntities.sline2d module

2D straight-line entity classes for UPXO.

Provides lightweight and full-featured 2D straight-line classes used in UPXO geometry construction, neighbourhood operations, meshing support, and geometric characterisation workflows.

Usage

from upxo.geoEntities.sline2d import Sline2d_leanest from upxo.geoEntities.sline2d import Sline2d from upxo.geoEntities.sline2d import Sline2d_leanest as sl2dl from upxo.geoEntities.sline2d import Sline2d as sl2d

Classes

Sline2d_leanest : Minimal 2D straight line (coordinates only, __slots__). Sline2d : Full-featured 2D straight line with geometric operations.

Notes

Coordinate system convention (right-hand, Y-up):

     Y+
     |           Z-
     |         /
X-   |       /        X+
-----O-----/----------
    /|
  /  |
Z+   Y-

class upxo.geoEntities.sline2d.Sline2d_leanest(x0=0, y0=0, x1=1, y1=0)

Bases: object

Lean 2D straight line class.

This is the minimal, lightweight representation of a 2D straight line in UPXO. It stores only endpoint coordinates (x0, y0) and (x1, y1) and provides essential geometric utilities such as: * line length * gradient * endpoint/index access * point containment checks relative to the finite segment

Compared to Sline2d, this class is intentionally compact and is suitable for high-volume geometry operations where only core line behavior is required.

x0, y0

Coordinates of start point.

Type:

float

x1, y1

Coordinates of end point.

Type:

float

Usage

-----

from upxo.geoEntities.sline2d import Sline2d_leanest as sl2dl

Examples

>>> from upxo.geoEntities.sline2d import Sline2d_leanest as sl2dl
>>> e = sl2dl(-2, 3, 4, 5)
>>> for coord in e:
...     print(coord)
>>> print(e[1])

x0

y0

x1

y1

classmethod by_coord(start, end)

Create Sline2d by specifying end coordinates.

Parameters:

• start (list of float) – Start point as [x0, y0].

• end (list of float) – End point as [x1, y1].

Returns:

Lean line connecting start and end.

Return type:

Sline2d_leanest

Examples

>>> from upxo.geoEntities.sline2d import Sline2d_leanest as sl2dlean
>>> A = sl2dlean.by_coord([-1, 2], [3, 4])

property length

Return length of self.

Returns:

Euclidean distance between (x0, y0) and (x1, y1).

Return type:

float

Examples

>>> from upxo.geoEntities.sline2d import Sline2d_leanest as sl2dl
>>> e = sl2dl(-2, 3, 4, 5)
>>> e.length

property gradient

Return the gradient of the self line.

Returns:

Slope (y1 - y0) / (x1 - x0), or math.inf for vertical lines.

Return type:

float

Examples

>>> from upxo.geoEntities.sline2d import Sline2d_leanest as sl2dl
>>> sl2dl(-2, 3, 4, 5).gradient
>>> sl2dl(0, 1, 0, 2).gradient

contains_point(obj=None)

Assess relative positioning of a point with respect to self edge. Output helps determine whether the point:

1. is fully contained inside the self edge

2. is coincident with one of the points of the self edge

3. is located on the extended part of the self edge

4. none of the above. Relative position unknown.

Parameters:

obj (coord, UPXO point2d object) – Represents a point in space. The default is None.

Notes

Point containment is exact (no tolerance). The method evaluates: * perpendicular distance of point from the line, * distances from point to line endpoints, and then classifies the position.

Returns:

intersection – Provides the relative position of point with respect to self edge.

1. Contains the point. It coincides with one of the edge points. The truth values in ‘intersection’ are [True, False, True]

2. Contains the point. Point is fully inside the edge. The truth values in ‘intersection’ are [True, False, False]

3. Point is on the extended edge. The truth values in ‘intersection’ are [False, True, False]

4. Relative position of point unknown. The truth values in ‘intersection’ are [False, False, False]

Return type:

[bool, bool, bool]

Examples

>>> from upxo.geoEntities.point2d import Point2d
>>> from upxo.geoEntities.sline2d import Sline2d_leanest as sl2dlean
>>> e = sl2dlean.by_coord([-1, 0], [1, 0])
>>> e.contains_point([-0.5, 0])
>>> e.contains_point(Point2d(-1.1, 1))

class upxo.geoEntities.sline2d.Sline2d(x0=0, y0=0, x1=1, y1=0, pnta=None, pntb=None)

Bases: object

Sline2d: 2D Straight line object.

Rich 2D line entity used across UPXO geometry, meshing and analysis workflows. In addition to endpoint coordinates, this class maintains UPXO point objects (pnta, pntb) and provides construction helpers, geometric properties, containment checks, splitting, translation and neighborhood utilities.

Use this class when mutable point objects, feature extraction or advanced geometric operations are needed. For lightweight coordinate-only behavior, use Sline2d_leanest.

Points are:

1. start (i.e. i): x0 & y0

2. end (i.e. j): x1 & y1

Following are the creation methods:

• Default creation is by specifying __init__(x0, y0, x1, y1).

• by_coord(start, end).

• by_point_slope(point, slope).

• by_slope_intercept(slope, intercept).

• by_parametric(point1, point2, N).

• by_coeff_const(a, b, c).

• by_vector(point, xyproj).

• by_loc_len_ang(ref=’i’, loc=[0, 0, 0], length=1, ang=0, degree=True).

• by_perp_bisector(line, point).

• by_transform(refedge=None, shiftxy=[0, 1], rot=+45, degree=True,

  rot_pnt_f=0.5).

• by_dist_bw_points(refpoint=None, points=None, f).

Following are the property attributes:

• length: Length of the line

• gradient: Gradient of the line

• mid: midpoint of the line

• ang: angle in radians

• angd: angle in degrees

• vert: True if line is vertical

• horz: True if horizontal

• lean: Return lean representation of self.

Usage

from upxo.geoEntities.sline2d import Sline2d

ε = 1e-08

pnta

pntb

x0

y0

x1

y1

classmethod by_coord(start, end)

Create Sline2d by specifying end coordinates.

Parameters:

• start (Starting point coordinate [x0, y0])

• end (Ending point coordinate [x1, y1])

Returns:

Line connecting start and end.

Return type:

Sline2d

Examples

from upxo.geoEntities.sline2d import Sline2d as sl2d
A = sl2d.by_coord([-1, 2], [3, 4])

classmethod by_p2d(start, end)

Create Sline2d by specifying end UPXO points.

Parameters:

• start (Starting point)

• end (Ending point)

Returns:

Line created from two UPXO point objects.

Return type:

Sline2d

Examples

>>> from upxo.geoEntities.point2d import Point2d as p2d
>>> from upxo.geoEntities.sline2d import Sline2d as sl2d
>>> sl2d.by_p2d(p2d(-1, 2), p2d(3, 4))

classmethod by_MCL(gradient, intercept, length)

Instantiate the Sline2d using slope, intercept and length.

Parameters:

• gradient (Slope of the 2D line)

• intercept (Y-intercept of the straight line)

• length (Length of the straight line)

Return type:

Instance of Sline2d

Examples

from upxo.geoEntities.sline2d import Sline2d
Sline2d.by_MCL(1.0, -1, 1)

classmethod by_MCLC(gradient, intercept, length, centre)

Instantiate Sline2d using m, c and L, centred at centre-(cx, cy).

Notes

MCLC stands for: Gradient (M), Y-intercept (C), Length (L), Centre (C).

Parameters:

• gradient (Slope of the 2D line)

• intercept (Y-intercept of the straight line)

• length (Length of the straight line)

• centre (Proposed x- and y-location of line midpoint: (cx, cy))

Return type:

Instance of Sline2d

Examples

from upxo.geoEntities.sline2d import Sline2d
Sline2d.by_MCLC(1.0, 0, 2.0, (-10.0, -10.0))
Sline2d.by_MCLC(1.0, -1.0, 2.0, (-10.0, -5.0))

classmethod by_parametric(point1, point2, N)

A line can be represented using parametric equations. line = [[x1 + t * (x2 - x1), y1 + t * (y2 - y1)] for t in range(n)]

Notes

To be developed.

classmethod by_general_form(A, B, C)

Instantiate a line represented in the general form (Ax+By+C=0).

line = [A, B, C]

Parameters:

• A (float) – Coefficients of the line equation Ax + By + C = 0.

• B (float) – Coefficients of the line equation Ax + By + C = 0.

• C (float) – Coefficients of the line equation Ax + By + C = 0.

Returns:

Constructed line consistent with the supplied general-form coefficients.

Return type:

Sline2d

Examples

from upxo.geoEntities.sline2d import Sline2d
Sline2d.by_general_form(1, 1, 0.2)

classmethod by_point_dxdy(start_point, dxdy)

A line can be represented using a point on the line and a dir. vector.

line = [[x, y], [dx, dy]]

Parameters:

• start_point (iterable) – Starting coordinate pair [x, y].

• dxdy (iterable) – Direction increments [dx, dy].

Returns:

Line from start_point to start_point + dxdy.

Return type:

Sline2d

Examples

from upxo.geoEntities.sline2d import Sline2d
Sline2d.by_point_dxdy([1, 1], [2, 3])

classmethod by_LFGL(location=[0, 0], factor=0.0, gradient=0, length=1, _skip_val_=False)

Create Sline2d by specifying location, factor, gradient and length.

Usage

from upxo.geoEntities.sline2d import Sline2d as sl2d

Notes

Gradient of math.inf (vertical line) causes a known line-creation issue.

Author: Dr. Sunil Anandatheertha

returns:

Line generated by location-factor-gradient-length specification.

rtype:

Sline2d

Examples

from upxo.geoEntities.sline2d import Sline2d as sl2d
sl2d.by_LFGL(location=[0, 0], factor=0.0, gradient=0, length=1)
sl2d.by_LFGL(location=[0, 0], factor=0.0, gradient=1, length=1)
sl2d.by_LFGL(location=[0, 0], factor=0.0, gradient=-1, length=1)
sl2d.by_LFGL(location=[0, 0], factor=1.0, gradient=0, length=1)
sl2d.by_LFGL(location=[0, 0], factor=0.0, gradient=math.inf, length=1)

classmethod by_LFAL(location=[0, 0], factor=0.0, angle=0, length=1, degree=True)

Create Sline2d by specifying location, factor, angle and length.

Parameters:

• ref (Specifies which point on the line is used to specify the edge.)

• loc (Specifies the ref point.)

• length (Length of the line to be made.)

• angle (this specifies a list of three angles. First)

• angle

• degree (ang considered in degree if degree is True, in radians if)

• otherwise.

Returns:

Line generated by location-factor-angle-length specification.

Return type:

Sline2d

Examples

from upxo.geoEntities.sline2d import Sline2d as sl2d
_cdef_ = sl2d.by_LFAL  # Class definition i.e. class method

loc = [0, 0]
_cdef_(location=loc, factor=0.0, angle=0, length=1, degree=True)
_cdef_(location=loc, factor=1.0, angle=0, length=1, degree=True)
_cdef_(location=loc, factor=0.5, angle=0, length=1, degree=True)

_cdef_(location=loc, factor=0.0, angle=90, length=1, degree=True)
_cdef_(location=loc, factor=0.0, angle=-90, length=1, degree=True)
_cdef_(location=loc, factor=1.0, angle=-90, length=1, degree=True)

loc = [10, 10]
_cdef_(location=loc, factor=0.0, angle=45, length=1, degree=True)
_cdef_(location=loc, factor=0.0, angle=-45, length=1, degree=True)
_cdef_(location=loc, factor=1.0, angle=45, length=1, degree=True)
_cdef_(location=loc, factor=1.0, angle=-45, length=1, degree=True)

_cdef_(location=loc, factor=0.5, angle=45, length=1, degree=True)
_cdef_(location=loc, factor=0.5, angle=-45, length=1, degree=True)
_cdef_(location=loc, factor=0.2, angle=45, length=1, degree=True)
_cdef_(location=loc, factor=0.8, angle=-45, length=1, degree=True)

classmethod by_perp_bisector(line, point)

Calculate and make the perpendicular bisector Sline2d b/w line and a point.

Parameters:

• e (Edge specification. Preferred: UPXO edge2d_leanest)

• p (Point specification. Preferred: UPXO point2d_leanest)

Examples

from upxo.geoEntities.point2d import Edge2d as e2d from upxo.geoEntities.point2d import edge2d_leanest from upxo.geoEntities.point2d import p2d_leanest

e = edge2d_leanest(-2, 3, 4, 5) e[1] p = p2d_leanest(1, 2)

from sympy import Point, Segment s = Segment(Point(e[0], e[1]), Point(e[2], e[3]))

Notes

To be developed.

classmethod by_transform(refedge=None, shiftxy=[0, 1], rot=45, degree=True, rot_pnt_f=0.5)

Calculate and make the new Sline2d by transforming refedge.

Parameters:

• refedge (Reference sline which is to be transformed. Preferably,) – provide UPXO edge2d object.

• shiftxy (Translation along x and y axes.)

• rot (Rotation angle about a point. This point location is determined) – using input rot_pnt_f. Positive value indicates CCW from x+ axis. Negative value indicated CW from x+ axis. Domain is [0, 180] and [-(180-eps), 0-eps], eps is very small number in python (value?).

• degree (If True, provided rot value will be considered in degrees,) – else, in radians.

• rot_pnt_f (Valid domain [0.0, 1.0]. This is a factor of length. For) – example, if rot_pnt_f = 0.25, then the point about which the edge shall be rotated by rot angle will be located at 25% length away from start (i.e, (x0, y0)) point of the refedge.

Notes

To be developed.

property mid_coord

Return midpoint coordinates of the line.

Returns:

Midpoint as [xmid, ymid].

Return type:

list

property mid_point

Return midpoint as a UPXO point object.

Returns:

Midpoint represented as Point2d.

Return type:

Point2d

property gradient

Return the slope of the line.

Returns:

Gradient of the line. Returns math.inf for vertical lines.

Return type:

float

Examples

>>> from upxo.geoEntities.sline2d import Sline2d as sl2d
>>> sl2d.by_coord([-1, 2], [3, 4]).gradient
>>> sl2d.by_coord([-1, -1], [1, 1]).gradient
>>> sl2d.by_coord([0, 0], [0, 1]).gradient
>>> sl2d.by_coord([0, 0], [1, 0]).gradient

property dxdy

Return the length increments along x and y.

Examples

>>> from upxo.geoEntities.sline2d import Sline2d as sl2d
>>> a = sl2d(0,0, 1,1)
>>> a.dxdy

property dx

Return the length increment along x.

Examples

>>> from upxo.geoEntities.sline2d import Sline2d as sl2d
>>> a = sl2d(0, 0, 1, 1)
>>> a.dx

property dy

Return the length increments along y.

Examples

>>> from upxo.geoEntities.sline2d import Sline2d as sl2d
>>> a = sl2d(0, 0, 1, 1)
>>> a.dy

property yint

Return the y-intercept of the line.

Returns:

Y-intercept if finite; math.inf for vertical lines.

Return type:

float

Examples

>>> from upxo.geoEntities.sline2d import Sline2d as sl2d
>>> sl2d.by_coord([-1, 2], [3, 4]).yint
>>> sl2d.by_coord([-1, -1], [1, 1]).yint
>>> sl2d.by_coord([0, 0], [0, 1]).yint
>>> sl2d.by_coord([0, 0], [1, 0]).yint
>>> sl2d.by_coord([0, -1], [1, -1]).yint

property ang

Return the ccw + angle in radians.

Returns:

Angle from positive x-axis to line direction in radians.

Return type:

float

Examples

>>> from upxo.geoEntities.sline2d import Sline2d as sl2d
>>> sl2d.by_coord([-1, 2], [3, 4]).ang
>>> sl2d.by_coord([-1, -1], [1, 1]).ang
>>> sl2d.by_coord([0, 0], [0, 1]).ang
>>> sl2d.by_coord([0, 0], [1, 0]).ang
>>> sl2d.by_coord([0, -1], [1, -1]).ang

property angd

Return the ccw + angle in degrees.

Returns:

Angle from positive x-axis to line direction in degrees.

Return type:

float

Examples

>>> from upxo.geoEntities.sline2d import Sline2d as sl2d
>>> sl2d.by_coord([-1, 2], [3, 4]).angd
>>> sl2d.by_coord([-1, -1], [1, 1]).angd
>>> sl2d.by_coord([0, 0], [0, 1]).angd
>>> sl2d.by_coord([0, 0], [1, 0]).angd
>>> sl2d.by_coord([0, -1], [1, -1]).angd

property length

Calculate and return self length.

Returns:

Euclidean distance between line endpoints.

Return type:

float

Examples

>>> from upxo.geoEntities.sline2d import Sline2d as sl2d
>>> sl2d.by_coord([-1, 2], [3, 4]).length
>>> sl2d.by_coord([-1, -1], [1, 1]).length
>>> sl2d.by_coord([0, 0], [0, 1]).length
>>> sl2d.by_coord([0, 0], [1, 0]).length
>>> sl2d.by_coord([0, -1], [1, -1]).length

property vert

Return True if the line is vertical.

Returns:

True when |x0 - x1| <= Sline2d.ε.

Return type:

bool

property horz

Return True if the line is horizontal.

Returns:

True when |y0 - y1| <= Sline2d.ε.

Return type:

bool

property lean

Return lean representation of self.

Returns:

Coordinate-only lean representation.

Return type:

Sline2d_leanest

property points

Return point – A, mid-point and point – B

Returns:

[pnta, mid_point, pntb] as UPXO point objects.

Return type:

list

property coords

Return coordinate array.

Returns:

Coordinates [x0, y0, x1, y1].

Return type:

list

Examples

>>> from upxo.geoEntities.sline2d import Sline2d as sl2d
>>> a = sl2d(0,0, 1,1)
>>> a.coords

property coord_list

Return coordinate array.

Returns:

Endpoint coordinates [[x0, y0], [x1, y1]].

Return type:

list

Examples

>>> from upxo.geoEntities.sline2d import Sline2d as sl2d
>>> a = sl2d(0,0, 1,1)
>>> a.coord_list

property coord_i

Return coordinates of starting point as [x0, y0].

property coord_j

Return coordinates of ending point as [x1, y1].

property general_form

Return coefficients of the general form of the self.

Returns:

Coefficients [A, B, C] for equation Ax + By + C = 0.

Return type:

list

Examples

from upxo.geoEntities.sline2d import Sline2d as sl2d
sl2d(0,0,0,1).general_form
sl2d(1,0,0,1).general_form
sl2d(-1.06,+10.6854,0.156,-1.685463).general_form

flip()

Flip the line coordinates and points. MIDs of point objects do not change, but only their coordinate values change.

Return type:

None

Examples

from upxo.geoEntities.sline2d import Sline2d as sl2d
a = sl2d(0,0,0,1)
a.flip()
a
a.coord_list

reset_coords_to_points()

When the points coordinates have been changed, either by changing the coordinates of the individual points or by changing the points itself, then use this to update the coordinates.

Return type:

None

reset_points_to_coords()

When the coordinates of the line end points have been updated, use this to update the point objects of the line.

Return type:

None

is_point_endpoint(point)

Return True if point is one of the end points on the line.

Examples

>>> from upxo.geoEntities.sline2d import Sline2d as sl2d
>>> sl2d(0,0,1,1).is_point_endpoint((0,0))
>>> sl2d(0,0,1,1).is_point_endpoint([1, 3])

invert()

Invert start and end points.

Examples

>>> from upxo.geoEntities.sline2d import Sline2d as sl2d
>>> a = sl2d(0,0,1,1)
>>> a.invert()
>>> a.coord_list

move_i(point)

Move start point of the line to a new coordinate.

Parameters:

point (iterable) – New start-point coordinate as (x, y).

move_j(point)

Move end point of the line to a new coordinate.

Parameters:

point (iterable) – New end-point coordinate as (x, y).

move_to_location(coord=None, ref='mid', saa=True, throw=False)

Move the line so that the reference point lands at coord.

Parameters:

• coord (list of float) – Target [x, y] coordinate.

• ref (str, optional) – Reference point on the line — 'mid', 'i', or 'j'.

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

• throw (bool, optional) – If True, return the resulting line.

Examples

from upxo.geoEntities.sline2d import Sline2d as sl2d

line = sl2d(0, 0, 1, 1)
line.move_to_location(coord=[0,0],ref='mid',saa=True,throw=False)
line

line = sl2d(0, 0, 1, 1)
line.move_to_location(coord=[0,0],ref='mid',saa=False,throw=True)
line

break_up(n)

Break self into n equal sub-lines.

Parameters:

n (int) – Number of sub-lines to create.

Examples

from upxo.geoEntities.sline2d import Sline2d as sl2d
line = sl2d(-3,-5,2,2)
n = 5
line.break_up(n)

fully_contains_point(p2d=None, method='through')

Return True if p2d lies strictly inside (not at endpoints of) self.

Parameters:

• p2d (Point2d or coordinate pair) – The point to test.

• method (str, optional) – 'simple' or 'through' (default).

Examples

from upxo.geoEntities.sline2d import Sline2d as sl2d
from upxo.geoEntities.point2d import Point2d
line = sl2d.by_coord([-1, 0], [1, 0])
points = [Point2d(0, 0), Point2d(-1, 0), Point2d(1, 0),
          Point2d(0.2, 1), Point2d(0.2, 0), Point2d(0, 1),
          Point2d(-1, 1), Point2d(1, 1)]
for point in points:
    print('LINE:', line, 'POINT:', point)
    print(line.fully_contains_point(point, method='through'))

contains_point(obj=None, return_bools=True)

Assess relative positioning of a point with respect to self edge. Output helps determine whether the point:

1. is fully contained inside the self edge

2. is coincident with one of the points of the self edge

3. is located on the extended part of the self edge

4. none of the above. Relative position unknown.

Parameters:

• obj (coord, UPXO point2d object) – Represents a point in space. The default is None.

• return_bools (bool, optional) – If True, return classification as a boolean triplet. If False, return classification as integer case id in [1, 4].

Notes

This method performs exact geometric checks (no tolerance parameter). It classifies the point with respect to the finite segment and its infinite extension.

Returns:

intersection – Provides the relative position of point with respect to self edge.

1. Contains the point. It coincides with one of the edge points. The truth values in ‘intersection’ are [True, False, True]. This is case number 1. A return_bools=False would return 1 if contains check operation results in [True, False, True].

2. Contains the point. Point is fully inside the edge. The truth values in ‘intersection’ are [True, False, False]. This is case number 2. A return_bools=False would return 2 if contains check operation results in [True, False, False].

3. Point is on the extended edge. The truth values in ‘intersection’ are [False, True, False]. This is case number 3. A return_bools=False would return 3 if contains check operation results in [False, True, False].

4. Relative position of point unknown. The truth values in ‘intersection’ are [False, False, False]. This is case number 4. A return_bools=False would return 4 if contains check operation results in [False, False, False].

Return type:

[bool, bool, bool]

Examples

from upxo.geoEntities.point2d import Point2d
from upxo.geoEntities.sline2d import Sline2d
pnta, pntb = Point2d(-1, 0), Point2d(1, 0)
e = Sline2d.by_p2d(pnta, pntb)

e.contains_point([-0.5, 0])
e.contains_point([-0.5, 0], return_bools=True)
e.contains_point([-0.5, 0], return_bools=False)
e.contains_point([0, 0])
e.contains_point([-1, 0])
e.contains_point([1, 0])
e.contains_point([-1.1, 0])
e.contains_point([-1.1, 1])

e.contains_point(Point2d(-0.5, 0))
e.contains_point(Point2d(0, 0))
e.contains_point(Point2d(-1, 0))
e.contains_point(Point2d(1, 0))
e.contains_point(Point2d(-1.1, 0))
e.contains_point(Point2d(-1.1, 1))

e = Sline2d(pnta=Point2d(1, 0), pntb=Point2d(1, 0))
e.contains_point([0.8, 0.2], return_bools=False)
e.contains_point(Point2d(0.8, 0.2))
e.contains_point(Point2d(0.8, 0.2), return_bools=False)

perpendicular_distance(point)

Compute perpendicular distance from a point to the infinite line.

Parameters:

point (Point2d) – Point for distance evaluation.

Returns:

Perpendicular distance from point to the line through self.

Return type:

float

contains_sl2d(obj=None, otype='sl2d')

Checks whether an edge is contained in self edge

Parameters:

• obj (Multiple types) –

  Point object or coordinate pair OR line object or pair of coordinate pairs. Accepts following types:

  • Coordinate pair * Pair of coordinate pair

  • UPXO point2d * UPXO edge object

  • Shapely point * Shapely line object

  • VTK point * VTK line object

  • GMSH point * GMSH line object

• otype (str) – Specify type of the object

Notes

Valid otype values used in this method are: * clist for coordinate pair-of-pairs * up2d for list/tuple of two UPXO points * sl2d for Sline2d instance

Returns:

Two truth value pairs. Description:

1st value: [bool1, bool2] 2nd value: [bool3, bool4] All values indicate location of points on the user input edge bool1:

True if pnta inside self edge True if pnta coincides with any of two self edge points False if pnta lies outside self edge

bool2:

True only if pnta of input edge lies on extended self edge

Third tuple item is a single bool indicating whether both end points of input line are contained in self.

Return type:

tuple( list(bool, bool), list(bool, bool) )

Notes

Set up the reference edge before running examples:

from upxo.geoEntities.point2d import Point2d
from upxo.geoEntities.sline2d import Sline2d
pnta, pntb = Point2d(0, 0), Point2d(1, 0)
e = Sline2d.by_p2d(pnta, pntb)

Examples

Example 1 — both endpoints inside:

obj = [[0.2, 0], [0.8, 0]]
k = e.contains_sl2d(obj=obj, otype='clist')
# k[0]=[True, False], k[1]=[True, False], k[2]=True

Example 2 — one endpoint outside:

obj = [[-0.1, 0], [1.0, 0]]
k = e.contains_sl2d(obj=obj, otype='clist')
# k[0]=[False, True], k[1]=[True, False], k[2]=False

Example 3 — first endpoint off the line:

obj = [[-0.1, 1], [1.0, 0]]
k = e.contains_sl2d(obj=obj, otype='clist')
# k[0]=[False, False], k[1]=[True, False], k[2]=False

Example 4 — endpoints coincide with self endpoints:

obj = [[0, 0], [1, 0]]
k = e.contains_sl2d(obj=obj, otype='clist')
# k[0]=[True, False], k[1]=[True, False], k[2]=True

Example 5 — degenerate (same point twice):

obj = [[0, 0], [0, 0]]
k = e.contains_sl2d(obj=obj, otype='clist')
# k[0]=[True, False], k[1]=[True, False], k[2]=True

Example 6 — UPXO point objects, both inside:

obj = [Point2d(0.2, 0), Point2d(0.8, 0)]
k = e.contains_sl2d(obj=obj, otype='up2d')
# k[0]=[True, False], k[1]=[True, False]

Example 7 — UPXO point objects, one outside:

obj = [Point2d(-0.1, 0), Point2d(1.0, 0)]
k = e.contains_sl2d(obj=obj, otype='up2d')
# k[0]=[False, True], k[1]=[True, False]

Example 8 — Sline2d object, inside:

obj = Sline2d(pnta=Point2d(0.1, 0), pntb=Point2d(0.5, 0))
k = e.contains_sl2d(obj=obj, otype='sl2d')
# k[0]=[False, True], k[1]=[True, False]

Example 9 — Sline2d object, one endpoint outside:

obj = Sline2d(pnta=Point2d(0.1, 0), pntb=Point2d(1.5, 0))
k = e.contains_sl2d(obj=obj, otype='sl2d')
# k[0]=[False, True], k[1]=[True, False]

distribute_points(n=5, spacing='constant', factor=0, sub_spacing='constant', subfactors=[0, 0], trim_ij=False, symexp=None, _coord_rounding_=(False, 8), _plot_=False)

Distribute points over a straight line.

Examples

from upxo.geoEntities.sline2d import Sline2d
line = Sline2d(0, 0, 0, 1)

line.distribute_points(n=9, spacing='constant', factor=0.5,
                       trim_ij=True, _plot_=True)
line.distribute_points(n=9, spacing='constant', factor=0,
                       trim_ij=True, _plot_=True)
line.distribute_points(n=[10, 10],
                       spacing='constant', factor=0.5,
                       sub_spacing=['cubic','cubic'],
                       subfactors=[0, 1],
                       trim_ij=True,
                       _coord_rounding_=(True, 8),
                       _plot_=True)

divide_at_ratios(ratios)

Divide self into sub-lines at the specified fractional positions.

Parameters:

ratios (float or list of float) – Fractional positions along the line in [0, 1].

Returns:

• points (list of Point2d)

• lines (list of Sline2d)

• mullines (MSline2d)

Examples

from upxo.geoEntities.sline2d import Sline2d as sl2d
LINE = sl2d(-3, -5, 2, 2)
ratios = [0.2, 0.3, 0.4]
points, lines, mullines = LINE.divide_at_ratios(ratios)
mullines.lines

move(dx, dy)

Translate line endpoints by uniform x and y increments.

Parameters:

• dx (float) – Translation along x-axis.

• dy (float) – Translation along y-axis.

is_normal(lines, _tol_decplace_=8)

Return Truth value list for normality check between self and lines.

Parameters:

• lines (Iterable of UPXO lines.)

• _tol_decplace_ (Number of rounding decimal places for gradient product) – check. Defaults to 8.

Examples

from upxo.geoEntities.sline2d import Sline2d as sl2d LINE = sl2d(-1.25, 1.068, 6.163, -8.012) nv1 = LINE.normal_vector(ratio=0.0, return_type=’sl2d’) nv2 = LINE.normal_vector(ratio=0.5, return_type=’sl2d’) nv3 = LINE.normal_vector(ratio=1.0, return_type=’sl2d’) LINE.is_normal((nv1, nv2, nv2))

normal_vector(ratio=0.0, return_type='sl2d')

Find normal vector centred at starting point.

Examples

from upxo.geoEntities.sline2d import Sline2d as sl2d
LINE = sl2d(-1.25, 1.068, 6.163, -8.012)
nv1 = LINE.normal_vector(ratio=0.0, return_type='sl2d')
nv2 = LINE.normal_vector(ratio=0.5, return_type='sl2d')
nv3 = LINE.normal_vector(ratio=1.0, return_type='sl2d')
LINE.is_normal((nv1, nv2))

normal = LINE.normal_vector(ratio=0.5, return_type='sl2d')
LINE.is_normal(normal)
LINE.distance_to_lines(normal, refi='i', refj='all')

generate_factors_0_and_1(dx1, dx2, dmean, k=0.0, th_res=0.001, max_iter=50)

Generate internal split factors between two boundary offsets in [0, 1].

Parameters:

• dx1 (float) – Left and right boundary offsets from 0 and 1 respectively.

• dx2 (float) – Left and right boundary offsets from 0 and 1 respectively.

• dmean (float) – Target mean spacing for generated factors.

• k (float, optional) – Relative random perturbation factor in [0, 0.25].

• th_res (float, optional) – Convergence tolerance on final residual.

• max_iter (int, optional) – Maximum attempts for stochastic convergence.

Returns:

Monotonic factors beginning at dx1 and ending near 1-dx2.

Return type:

numpy.ndarray

stretch(point, sf)

Scale self about a fixed point by the given scale factor.

Parameters:

• point (list of float) – Fixed point [x, y] about which scaling is applied.

• sf (float) – Scale factor.

Examples

from upxo.geoEntities.sline2d import Sline2d
line = Sline2d(0, 0, 1, 0)
line.stretch([0, 0], 1)
line
line.stretch([0, 0], 0.5)
line
line.stretch([0.5, 0], 0.5)
line
line.stretch([0, 0], 1)
line

distribute_normal_vectors(method='by_spacing', spacing_opt={'_coord_rounding_': (True, 8), '_plot_': True, 'factor': 0.5, 'n': [10, 10], 'spacing': 'constant', 'sub_spacing': ['cubic', 'cubic'], 'subfactors': [0, 1], 'trim_ij': True}, points=None, ratios=None, perform_checks=False, _check_eps_=1e-08)

Distribute normal vectors along self at selected positions.

Parameters:

• method (str, optional) – How positions are determined: 'by_spacing', 'by_points', or 'by_ratios'. Defaults to 'by_spacing'.

• spacing_opt (dict, optional) – Options for 'by_spacing' (see Examples).

• points (list, optional) – Pre-computed positions for 'by_points'.

• ratios (list of float, optional) – Fractional positions in [0, 1] for 'by_ratios'.

• perform_checks (bool, optional) – Validate normality of computed vectors. Defaults to False.

• _check_eps_ (float, optional) – Tolerance for normality check. Defaults to 1e-8.

Returns:

Normal vector lines placed at each selected position.

Return type:

list of Sline2d

Examples

Example 1 — default spacing:

from upxo.geoEntities.sline2d import Sline2d
import numpy as np
line = Sline2d(*np.random.randint(-10, 20, 4))
normals = line.distribute_normal_vectors()
line.plot(sl2d=normals)

Example 2 — constant sub-spacing:

spacing_opt = {'n': [10, 10], 'spacing': 'constant',
               'factor': 0.25, 'sub_spacing': ['constant', 'constant'],
               'subfactors': [0, 1], 'trim_ij': True,
               '_coord_rounding_': (True, 8), '_plot_': True}
normals = line.distribute_normal_vectors(method='by_spacing',
                                         spacing_opt=spacing_opt)
line.plot(sl2d=normals)

Example 3 — quadratic sub-spacing:

spacing_opt = {'n': [10, 10], 'spacing': 'constant',
               'factor': 0.25, 'sub_spacing': ['constant', 'quadratic'],
               'subfactors': [0, 1], 'trim_ij': True,
               '_coord_rounding_': (True, 8), '_plot_': True}
normals = line.distribute_normal_vectors(method='by_spacing',
                                         spacing_opt=spacing_opt)
line.plot(sl2d=normals)

Example 4 — cubic sub-spacing:

spacing_opt = {'n': [10, 50], 'spacing': 'constant',
               'factor': 0.25, 'sub_spacing': ['constant', 'cubic'],
               'subfactors': [0, 1], 'trim_ij': True,
               '_coord_rounding_': (True, 8), '_plot_': True}
normals = line.distribute_normal_vectors(method='by_spacing',
                                         spacing_opt=spacing_opt)
line.plot(sl2d=normals)

Example 5 — using pre-distributed points:

from upxo.geoEntities.sline2d import Sline2d
line = Sline2d(0, 0, 1, 0)
points = line.distribute_points(n=[10, 10], spacing='constant',
                                factor=0.5,
                                sub_spacing=['cubic', 'cubic'],
                                subfactors=[0, 1], trim_ij=True,
                                _coord_rounding_=(True, 8),
                                _plot_=False)
normals = line.distribute_normal_vectors(method='by_points',
                                         points=points)
line.plot(sl2d=normals)

Example 6 — using stochastic factor spacing:

from upxo.geoEntities.sline2d import Sline2d
import numpy as np
line = Sline2d(*np.random.randint(-10, 20, 4))
f = line.generate_factors_0_and_1(dx1=0.15, dx2=0.15,
                                  dmean=0.15, k=0.2, th_res=0.02)
points, lines, mullines = line.divide_at_ratios(f)
normals = line.distribute_normal_vectors(method='by_points',
                                         points=points)
for normal in normals:
    normal.stretch(normal.mid_coord, 10)
line.plot(sl2d=normals)

plot(p2d=None, sl2d=None)

Quick-plot self line with optional additional points and lines.

Parameters:

• p2d (Point2d or iterable, optional) – Point(s) to overlay.

• sl2d (Sline2d or iterable, optional) – Line(s) to overlay.

distance_to_points(points=None, *, ref='all')

Calculate the Baudhāyana distance between self and list of points.

Parameters:

• points (List of points)

• ref (Refers to point(s) location on the sline. Options include:) –

  • ‘all’: uses location i, j and the mid on the line.

  • ’i’: starting point, (x0, y0)

  • ’j’: starting point, (x1, y1)

  • ’mid’: middle point.

Returns:

Distances from the selected self reference location(s) to input points. For ref=’all’, returns three distance arrays/lists for start, midpoint and end respectively.

Return type:

list or numpy.ndarray

Examples

import numpy as np
from upxo.geoEntities.point2d import Point2d as p2d
from upxo.geoEntities.sline2d import Sline2d as sl2d
line = sl2d(0, 0, 1, 0)
points = [p2d(xy[0], xy[1]) for xy in np.random.random((10, 2))]
line.distance_to_points(points, ref='all')
line.distance_to_points(points, ref='i')
line.distance_to_points(points, ref='mid')
line.distance_to_points(points, ref='j')

distance_to_lines(lines=None, method='ref', refi='mid', refj='mid')

Calculate the Baudhāyana distance between self and list of edges.

Parameters:

• lines (List of lines)

• method (Indicate the method of calculation. Can take following values:) –

  • ‘ref’: Use the reference location specifiers to calculate

  distance. That is, use refi and refj. * ‘min’: Minimum Baudhāyana distance * ‘max’: MAximum Baudhāyana distance * ‘mean’: Mean Baudhāyana distance

• refi (reference location for self i.e. i)

• refj (referecne location for the other edge i.e. j)

Notes

Current implementation computes pairwise Euclidean distances between selected reference points only. The method argument is currently not branched into min/max/mean logic inside this function.

Return type:

List of ndarray distances to all edges.

Examples

from upxo.geoEntities.sline2d import Sline2d as sl2d
rline = sl2d(0, 0, 1, 0)
lines = [sl2d(0, i, 1, i) for i in range(1, 10)]
rline.distance_to_lines(lines, refi='mid', refj='all')

translate_by(*, vector=None, refloc='i', dist=None, update=False, throw=True)

Translate the Edge by a Euclidean distance.

Translate the Edge along the vector by a given distance. If update is True, then coords of the self will be updated.

If throw is True and update is False, a new edge of the new coordinates shall be returned. If throw is True and update is True, a deepcopy of the self shall be returned.

Notes

Phase 1: Without any validations (current implementation).

Parameters:

• vector (Direction of translation. Two specifications allowed are:) –

  Specification 1: [vector start point coords,

  vector end point coords]

  Specification 2: ‘x+’, ‘z-’

• dist (Euclidean distance. If None and not a Number, then the) – translation distance will be the length of the vector. If a number, then dist will be the translation distance, in which case the vector will only be used to know the translation direction.

• update (Update the current point if True, do not update if False.)

• throw (Return a edge if True, else return nothing if False.)

Returns:

• UPXO edge object (Conditional, depending on input throw (refer to) – description).

• Author

• ——

• Dr. Sunil Anandatheertha

Examples

Notes

To be developed.

intersection_lines(lines, dim=2)

Notes

Development milestones:

• All in lines are UPXO type 2D line objects.

• Consider 2D coordinate listings

• Consider UPXO type 3D line objects.

• Consider 3D coordinate listings

Parameters:

• lines (Data representing 2D and/or 3D lines.)

• dim (dimensionality. Default to 2. Options are:) – 2: 2D. 3: 3D. 4: 2D/3D - indicates mixed collection in lines user input.

Examples

from upxo.geoEntities.sline2d import Sline2d as sl2d
lines = [sl2d.by_coord([-1, -1], [3, 3]),
         sl2d.by_coord([-1, 1], [1, -1]),
         sl2d.by_coord([0, 0], [1, 0]),
         sl2d.by_coord([0, 0], [0, 1])]
sl2d.by_coord([0, 0], [0, 1]).intersection_lines(lines)
sl2d.by_coord([1, 0], [1, 1]).intersection_lines(lines)

rectangle(width, vis=False)

Return rectangle form of line.

Convert self line into rectangle of length equal to line.length and width equal to the user specified width. Rectangle will completely bound the line. Ednd points of line will be at midpoints of corresponding opposite lines of the rectangle.

Parameters:

• width (width of the rectangle.)

• vis (bool, optional) – If True, plot a quick visualization of line and rectangle.

Returns:

• coords (list of [p1, p2, p3, p4]. CCW from lower left point, p1.)

• rectangle (Shapely polygon object)

Examples

from upxo.geoEntities.sline2d import Sline2d as sl2d

# Horizontal lines
line = sl2d(0, 0, 1, 0)
_, r = line.rectangle(1, vis=True)
line = sl2d(1, 0, 0, 0)
_, r = line.rectangle(1, vis=True)

# Diagonal lines
line = sl2d(0, 0, 1, 1)
_, r = line.rectangle(1, vis=True)
line = sl2d(1, 1, 0, 0)
_, r = line.rectangle(1, vis=True)
line = sl2d(-1, -1, 1, 1)
_, r = line.rectangle(1, vis=True)
line = sl2d(1, -1, -1, 1)
_, r = line.rectangle(1, vis=True)

identify_points_in_rectangle(points, width=None, boundary_points=True, vis=False)

Identify points which lie inside rectangle of the line.

For a given set of points list, this function returns the indices of those points which are inside (and, on) the boundary of rectangle made from the self line (using width, of course).

Parameters:

• points (coordinates as [[x-coords],[y-coords]])

• width (rectangle width)

• boundary_points (If True, points on the boundary of the rectangle will) – be considered, else not.

• vis (If True, a quick visualization will be provided. Green is for) – self line, where smaller is starting point i and larger is ending point j. Marker sizes indicating corners of rectangle follow shapely polygon coordinate order. Black dots are points. Blue crosses are points which satisfy the geometric condition. NOTE: The above order may differ from UPXO line.rectangle.

Returns:

inside – points which satisfy the geometric criteria.

Return type:

Numpy arrau of bools. A True indicates position in input

Notes

The rectangle is created from self.rectangle(width). If boundary_points=True, points on polygon boundaries are included.

Examples

Example 1 — horizontal line:

import numpy as np
from upxo.geoEntities.sline2d import Sline2d as sl2d
line = sl2d(0, 0, 1, 0)
_x, _y = np.arange(0, 1, 0.1), np.arange(0, 1, 0.1)
x, y = np.meshgrid(_x, _y)
inside = line.identify_points_in_rectangle(
    [x.ravel(), y.ravel()], width=1, boundary_points=True, vis=True)

Example 2 — reversed horizontal line:

line = sl2d(-1, 0, 1, 0)
_x, _y = np.arange(0, 1, 0.1), np.arange(0, 1, 0.1)
x, y = np.meshgrid(_x, _y)
points = [x.ravel(), y.ravel()]
inside = line.identify_points_in_rectangle(points, 1, True, True)

Example 3 — oblique line:

line = sl2d(-1, 1, 1, 0)
x, y = np.meshgrid(np.arange(0, 1, 0.1), np.arange(0, 1, 0.1))
points = [x.ravel(), y.ravel()]
inside = line.identify_points_in_rectangle(points, 1, True, True)

Example 4 — vertical line:

line = sl2d(0, 0, 0, 1)
x, y = np.meshgrid(np.arange(0, 1, 0.1), np.arange(0, 1, 0.1))
points = [x.ravel(), y.ravel()]
inside = line.identify_points_in_rectangle(points, 1, True, True)

Example 5 — diagonal line, wider grid:

line = sl2d(1, -1, -1, 1)
x, y = np.meshgrid(np.arange(-2, 2, 0.1), np.arange(-2, 2, 0.1))
points = [x.ravel(), y.ravel()]
inside = line.identify_points_in_rectangle(points, 1, True, True)

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

Translate self to the specified location.

New location is specified by point object. POint object could be specified by an another UPXO point object or an Iterable of coords.

If throw is True and update is False, a new point of the new coordinates shall be returned. If throw is True and update is True, a deepcopy of the self shall be returned.

Parameters:

• ref (Location on the edge which translates to new point. Values of ref)

• be (could) –

  • ‘i’: Starting point of the edge

  • ’j’: Ending point of the edge

  • ’mid’: Middle point of the edge

  • [x, y, (z)]: Coordinate value

• point (New position. UPXO / direct point specification.)

• update (Update the current point if True, do not update if False.)

• throw (Return a point if True, else return nothing if False.)

Returns:

UPXO point object – description).

Return type:

Conditional, depending on input throw (refer to

Notes

To be developed.

rotate_about(*, axis=None, angle=0, degree=True, update=False, throw=True)

Rotate point about the specified axis by the specified angle.

New location is specified by point object. Point object could be specified by an another UPXO point object or an Iterable of coords.

If throw is True and update is False, a new point of the new coordinates shall be returned. If throw is True and update is True, a deepcopy of the self shall be returned.

Parameters:

• axis (Axis of rotation. Two specifications allowed are:) –

  Specification 1: [axis start point coords,

  axis end point coords]

  Specification 2: ‘x+’, ‘z-’

• angle (Counter-Clockwise positive, angle of rotation)

• degree (angle considered in degrees if True, radians if False.)

• update (Update the current point if True, do not update if False.)

• throw (Return a point if True, else return nothing if False.)

Returns:

UPXO point object – description).

Return type:

Conditional, depending on input throw (refer to

Notes

To be developed.

attach_mp(*, mp=None, name=None)

Attach a UPXO multi-point object and a name.

attach_xtal(*, xtals=None)

Attach a list of UPXO xtal objects.

Notes

To be developed.

perp_distance(plist, ptype='coord_list')

Examples

Example 1 — coordinate pair:

from upxo.geoEntities.sline2d import Sline2d as sl2d
line = sl2d(0, 0, 1, 1)
plist = (0.1, 0.1)
line.perp_distance(plist)

Example 2 — numpy array of coordinates:

import numpy as np
from upxo.geoEntities.sline2d import Sline2d as sl2d
line = sl2d(0, 0, 1, 0.0)
plist = np.random.random((4, 2)).T
line.perp_distance(plist)

Example 3 — list of Point2d objects:

from upxo.geoEntities.sline2d import Sline2d as sl2d
from upxo.geoEntities.point2d import Point2d as p2d
line = sl2d(0, 0, 1, 0.0)
plist = [p2d(1, 1), p2d(1, 2), p2d(1, 3), p2d(1, 4), p2d(1, 5)]
line.perp_distance(plist, ptype='[point2d]')

find_neigh_point_by_perp_distance(points=None, r=0.25, use_bounding_rec=False, epsfactor=100.0, vis=False)

Find the neighbouring point(s) in a list of points by perp distance.

Point subselection depends on whether a point is within OR on the cut-off perpendicular distance, r.

Parameters:

• points (Elements of points must contain the coordinates either in direct)

• [x (Iterable form (such a list of)

• np.array([x (y] or a nparray)

• y]))

• object. (OR a 2D/3D UPXO point)

• r (Cut-off perpendicular diatance.) – If 0, the closest point will be looked out for. If > 0, all points which fall in or on a circle of radius r will be looked out for.

• use_bounding_rec (bool, optional) – If True, perform candidate filtering using rectangle containment around the line with width r (plus optional epsilon padding).

• epsfactor (float, optional) – Multiplier for Sline2d.ε when expanding rectangle width in bounding-rectangle mode.

• vis (bool, optional) – If True, plot the selected neighboring points.

Returns:

Indices in points satisfying selection criteria. Empty list if no points are inside cut-off.

Return type:

list

Examples

Example 1 — horizontal line, no bounding rectangle:

import numpy as np
from upxo.geoEntities.sline2d import Sline2d as sl2d
line = sl2d(0, 0, 1, 0)
x, y = np.meshgrid(np.arange(0, 1, 0.1), np.arange(0, 1, 0.1))
points = (x.ravel(), y.ravel())
line.find_neigh_point_by_perp_distance(
    points, 0.2, use_bounding_rec=False, epsfactor=1E6, vis=True)

Example 2 — reversed horizontal line, with bounding rectangle:

line = sl2d(0, 0, -1, 0)
x, y = np.meshgrid(np.arange(-0.2, 1, 0.1), np.arange(-0.2, 1, 0.1))
points = (x.ravel(), y.ravel())
line.find_neigh_point_by_perp_distance(
    points, 0.2, use_bounding_rec=True, epsfactor=0, vis=True)
line.find_neigh_point_by_perp_distance(
    points, 0.2, use_bounding_rec=True, epsfactor=1E7, vis=True)

Example 3 — diagonal line:

line = sl2d(0, 0, 1, 0.5)
x, y = np.meshgrid(np.arange(0, 1, 0.1), np.arange(0, 1, 0.1))
points = (x.ravel(), y.ravel())
line.find_neigh_point_by_perp_distance(
    points, 0.2, use_bounding_rec=True, epsfactor=0, vis=True)

Example 4 — oblique line with negative start:

line = sl2d(-0.5, -1, 1, 0.5)
x, y = np.meshgrid(np.arange(-0.2, 1, 0.1), np.arange(-0.2, 1, 0.1))
points = (x.ravel(), y.ravel())
line.find_neigh_point_by_perp_distance(
    points, 0.2, use_bounding_rec=True, epsfactor=0, vis=True)
line.find_neigh_point_by_perp_distance(
    points, 0.2, use_bounding_rec=False, epsfactor=0, vis=True)

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

Find n nearest neighbouring points in a specified list of points.

Parameters:

• plist (Elements of plist must contain the coordinates either in direct)

• [x (Iterable form (such a list of)

• np.array([x (y] or a nparray)

• y]))

• object. (OR a 2D/3D UPXO point)

• n (Number of nearest neighbours to return. If not entered, a single)

• returned. (point shall be)

• plane (Specify the plane of the self point. Only used if self is a 2D)

• 'xy'. (point object. Defaults to)

Return type:

Indices in plist.

Notes

To be developed.

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

Find the nearest UPXO multi-point in specified list of UPXO mulpoints.

If tolerance factor, tolf is provided to be -1, then, even if a single point in a mp falls in or on r, the index of mp in mplist will be added to the list to be returned. If 0 < tolf <= 1, then even if tolf factor of total number of points in a mp falls inside r, then the index of this mp in mplist will be added to the list to be returned.

Parameters:

• mplist (Elements of plist must contain the coordinates either in direct)

• [x (Iterable form (such a list of)

• np.array([x (y] or a nparray)

• y]))

• object. (OR a 2D/3D UPXO point)

• plane (Specify the plane of the self point. Only used if self is a 2D)

• 'xy'. (point object. Defaults to)

• r (Euclidean radius of search.) – If 0, the closest point will be looked out for. If > 0, all points which fall in or on a circle of radius r will be looked out for.

Return type:

Indices in mplist.

Notes

To be developed.

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

Find the nearest UPXO edge in specified list of UPXO edges.

Parameters:

• elist (Elements of elist must contain edges in either of the following) –

  two formats:

  1. 2D/3D UPXO edge objects.

  2. Iterable object with elements starting point: [x0, y0, z0] and ending point: [x1, y1, z1]

• plane (Specify the plane of the self point. Only used if self is a 2D)

• 'xy'. (point object. Defaults to)

• refloc (Specify the location on th edge which is to be used for)

• It (calculating the distance form the self point itself and the edge.)

• options (can have the following) –

  • ‘starting’. Starting point of the edge. Alternative use: start

  • ’ending’. Ending point of the edge. Alternative use: end

  • ’middle’. Mid point of the edge. Alternative use: mid

  • ’any’. Any point of the edge. No alternate.

  • ’all’. Both start and end points of the edge. No alternate.

• r (Euclidean radius of search.) – If 0, the closest point will be looked out for. If > 0, all points which fall in or on a circle of radius r will be looked out for.

Return type:

Indices in mplist.

Notes

To be developed.

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

Find the nearest UPXO muledge in specified list of UPXO muledges.

Parameters:

• melist (Elements of melist must contain medges in either of the)

• format (following single) –

  1. 2D/3D UPXO medge objects.

• plane (Specify the plane of the self point. Only used if self is a 2D)

• 'xy'. (point object. Defaults to)

• refloc (Specify the location on th edge which is to be used for)

• It (calculating the distance form the self point itself and the edge.)

• options (can have the following) –

  • ‘starting’. Starting point of the edge. Alternative use: start

  • ’ending’. Ending point of the edge. Alternative use: end

  • ’middle’. Mid point of the edge. Alternative use: mid

  • ’any’. Any point of the edge. No alternate.

  • ’all’. Both start and end points of the edge. No alternate.

• r (Euclidean radius of search.) – If 0, the closest point will be looked out for. If > 0, all points which fall in or on a circle of radius r will be looked out for.

Return type:

Indices in mplist.

Notes

To be developed.

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

Find the nearest UPXO xtal in specified list of UPXO xtals.

Parameters:

• xlist (Elements of xlist must contain xtals in either of the)

• formats (following three) –

  1. 2D/3D UPXO xtal objects.

  2. Shapely polygon object.

  3. GMSH closed region.

  4. VTK polyhedra object.

• plane (Specify the plane of the self point. Only used if self is a 2D)

• 'xy'. (point object. Defaults to)

• refloc (Specify the location on th edge which is to be used for)

• It (calculating the distance form the self point itself and the edge.)

• options (can have the following) –

  • ‘starting’. Starting point of the edge. Alternative use: start

  • ’ending’. Ending point of the edge. Alternative use: end

  • ’middle’. Mid point of the edge. Alternative use: mid

  • ’any’. Any point of the edge. No alternate.

  • ’all’. Both start and end points of the edge. No alternate.

• r (Euclidean radius of search.) – If 0, the closest point will be looked out for. If > 0, all points which fall in or on a circle of radius r will be looked out for.

Return type:

Indices in mplist.

Notes

To be developed.

find_colinear_lines(lines, line_repr='upxo')

Find lines collinear to self from a given collection.

Parameters:

• lines (list) – Collection of lines (UPXO objects or coordinate lists).

• line_repr (str, optional) – 'upxo' or 'coord_list'.

Returns:

Indices of collinear lines, or None if none found.

Return type:

list or None

Examples

Example 1 — UPXO line objects:

from upxo.geoEntities.sline2d import Sline2d as sl2d
line = sl2d(0, 0, -1, 0)
lines = [sl2d(0, 0, -1, 0), sl2d(0, 0, 1, 2),
         sl2d(-1, 0, -2, 0), sl2d(4, 0, 3, 0),
         sl2d(0, 0, 1, 0), sl2d(0, 1, 1, 1)]
line.find_colinear_lines(lines, line_repr='upxo')

Example 2 — coordinate list:

from upxo.geoEntities.sline2d import Sline2d as sl2d
line = sl2d(2, 7, 7, 3)
lines = [[[0, 9], [0, 1]], [[1, 8], [6, 2]],
         [[3, 8], [8, 4]], [[3, 6], [8, 4]]]
line.find_colinear_lines(lines, line_repr='coord_list')

Example 3 — coordinate list, horizontal:

from upxo.geoEntities.sline2d import Sline2d as sl2d
line = sl2d(0, 0, -1, 0)
lines = [[[0, 0], [-1, 0]], [[0, 0], [1, 2]],
         [[-1, 0], [-2, 0]], [[4, 0], [3, 0]],
         [[0, 0], [1, 0]], [[0, 1], [1, 1]],
         [[0, 0], [-1, 0]]]
line.find_colinear_lines(lines, line_repr='coord_list')

find_parallel_lines(lines, line_repr='upxo')

Find line amongst lines parallel to self.

Parameters:

• lines (list of data representing lines)

• line_repr (specifies the type of line representation. Valid) –

  options include (see examples below for specific information.):

  • ’upxo’

  • ’coord_list’

Return type:

Location indices of those lines in lines parallel to self.

Examples

Example 1 — UPXO line objects:

from upxo.geoEntities.sline2d import Sline2d as sl2d
line = sl2d(0, 0, -1, 0)
lines = [sl2d(0, 0, -1, 0), sl2d(0, 0, 1, 2)]
line.find_parallel_lines(lines, line_repr='upxo')

Example 2 — coordinate list:

from upxo.geoEntities.sline2d import Sline2d as sl2d
line = sl2d(2, 7, 7, 3)
lines = [[[0, 9], [0, 1]], [[1, 8], [6, 2]],
         [[2, 7], [7, 3]], [[3, 6], [8, 4]]]
line.find_parallel_lines(lines, line_repr='coord_list')

make_points(n, spacing='linear', threshold_factor=1.0, start='i', store_as_feature=False, feature_replace=False, vis=False)

Make n points on the line.

Parameters:

• n (Number of points to make)

• spacing (mathematical spacing to apply)

• threshold_factor

• start (spacifies the location about which point creation starts.)

• store_as_feature (If True, points will be stored in self.f dictionary.) – Defaults to False.

• feature_replace (If True, any existing feature points will be erased.) – DEfaults to False.

• vis (If True, result shall be visualized. Defaults to False.)

Returns:

• points

• increments

Examples

Example 1 — linear spacing:

from upxo.geoEntities.sline2d import Sline2d as sl2d
line = sl2d(-1, -1, 1, 1)
line.make_points(10, spacing='linear', threshold_factor=1.0, vis=True)

Example 2 — quadratic spacing:

from upxo.geoEntities.sline2d import Sline2d as sl2d
line = sl2d(-1, -1, 1, 1)
line.make_points(5, spacing='quadratic', threshold_factor=1.0, vis=True)

Example 3 — reduced threshold:

from upxo.geoEntities.sline2d import Sline2d as sl2d
line = sl2d(-1, -1, 1, 1)
line.make_points(5, spacing='linear', threshold_factor=0.5, vis=True)

Example 4 — start from endpoint j:

from upxo.geoEntities.sline2d import Sline2d as sl2d
line = sl2d(-1, -1, 1, 1)
line.make_points(5, spacing='linear', threshold_factor=0.5,
                 start='j', vis=True)

set_gmsh_props(prop_dict)

Set dictionary of gmsh properties.

Notes

To be developed.

make_shapely()

Return shapely point object. Only valid for 2D.

Notes

To be developed.

make_vtk()

Make VTK line object.

Notes

To be developed.

generate_points(dxmean, pert_factor=0.0)

dxmean : Mean spacing pert_factor

Examples

>>> from upxo.geoEntities.sline2d import Sline2d
>>> line = Sline2d(0, 0, 1, 1)
>>> line.generate_points(np.sqrt(2)/10, pert_factor=1)

translate_along_normals(method='by_distances', nlines=1, pert=0.0, spacing=1.0, dmax=None)

Translate self along its normal direction to produce offset copies.

Parameters:

• method (str) – 'by_distances' or 'by_count'.

• nlines (int, list, or nested list) – Number of copies or explicit distances per side.

• pert (float, optional) – Random perturbation fraction [0, 0.25].

• spacing (float or dict, optional) – Uniform spacing or normal-distribution dict {'dist': 'normal', 'mean': ..., 'std_factor': ...}.

• dmax (list of float, optional) – Maximum cumulative distance per side for 'by_count'.

Returns:

Offset line copies.

Return type:

list of Sline2d

Examples

from upxo.geoEntities.sline2d import Sline2d
line = Sline2d(-0.5, -1, 1, 0.5)

lines = line.translate_along_normals(method='by_count', nlines=[3, 2])
line.plot(sl2d=lines)

lines = line.translate_along_normals(method='by_distances',
                                     nlines=[[1.0, 2.0], [1.5, 3.0]],
                                     pert=0.1)
line.plot(sl2d=lines)

spacing = {'dist': 'normal', 'mean': 0.25, 'std_factor': 0.025}
lines = line.translate_along_normals(method='by_count', nlines=[5, 5],
                                     spacing=spacing)
line.plot(sl2d=lines)

spacing = {'dist': 'normal', 'mean': 0.25, 'std_factor': 0.1015}
lines = line.translate_along_normals(method='by_count', nlines=[20, 20],
                                     spacing=spacing, dmax=[12.5, 12.5])
line.plot(sl2d=lines)

f

translate_along_normals_2(method='by_distances', d=1, perturbation=0.0)

Alternate normal-translation implementation (unit spacing for by_count).

Parameters:

• method (str) – 'by_distances' or 'by_count'.

• d (list) – Two-element list of distances or counts per side.

• perturbation (float, optional) – Perturbation fraction [0, 0.25] for 'by_distances'.

Returns:

Translated line copies.

Return type:

list of Sline2d

Examples

from upxo.geoEntities.sline2d import Sline2d
line = Sline2d(-0.5, -1, 1, 0.5)

translated_lines = line.translate_along_normals_2(
    method='by_count', d=[3, 2])
line.plot(sl2d=translated_lines)

translated_lines = line.translate_along_normals_2(
    method='by_distances', d=[[1.0, 2.0], [1.5, 3.0]],
    perturbation=0.1)
line.plot(sl2d=translated_lines)

translate_along_normals_1(d=1)

Translate self by fixed distances on each normal side.

Parameters:

d (float or list of float) – Distance(s) for each side. Scalar applies same distance both sides; [d0, d1] applies d0 on one side and d1 on the other.

Returns:

Two offset lines, one per normal side.

Return type:

list of Sline2d

Examples

from upxo.geoEntities.sline2d import Sline2d
line = Sline2d(-0.5, -1, 1, 0.5)
line.translate_along_normals_1(d=[1, 20])

line = Sline2d(-0.5, 0, 0.5, 0)
line.plot(sl2d=line.translate_along_normals_1(d=[1, 3]))

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

Make an array of points by repeat-translating self.

Parameters:

• ncopies

• vector

• spacing

Return type:

list of point objects

Examples

Example 1 — translate along y-axis:

from upxo.geoEntities.sline2d import Sline2d
line = Sline2d(-0.5, -1, 1, 0.5)
lines = line.array_translation(ncopies=2, vector=[0, 1],
                               spacing='constant')
line.plot(sl2d=lines)

Example 2 — translate along normal direction:

from upxo.geoEntities.sline2d import Sline2d
line = Sline2d(-0.5, -1, 1, 0.5)
nv = line.normal_vector(ratio=0.0, return_type='sl2d')
lines = line.array_translation(ncopies=1, vector=[nv.x0, nv.y0],
                               spacing='constant', trim_self=True)
line.plot(sl2d=lines)

Example 3 — translate along both normal directions:

from upxo.geoEntities.sline2d import Sline2d
line = Sline2d(-0.5, -1, 1, 0.5)
nv = line.normal_vector(ratio=0.0, return_type='sl2d')
lines_A = line.array_translation(ncopies=1, vector=[nv.x0, nv.y0],
                                 spacing='constant', trim_self=True)
lines_B = line.array_translation(ncopies=1, vector=[-nv.x0, -nv.y0],
                                 spacing='constant', trim_self=True)
line.plot(sl2d=lines_A + lines_B)

lies_on_which_edge(*, elist=None, consider_ends=True)

Get indices from a list of edges, which contain the self point.

The point could lie on the end points of an edge or in-between the two end points of an edge.

Parameters:

• elist (list of edge objects)

• consider_ends (If True, index of the edge containing the selfpoint)

• False (coordinates at one of its end points will also be returned. If)

:param : :param the index will be included only if the point is not on the end: :param points but completely inside the edge’s end points.:

Return type:

List of indices of points which satisfy the condition.

Notes

To be developed.

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

Get indices from a list of xtals, which contain the self point.

The point could lie inside the xtal, on the boundaries of the xtal or on one of the end points of the many edges of the xtal.

Parameters:

• xlist (list of edge objects)

• consider_boundary (If True, search will be carried out to see if the)

• this (self point lies on one of the boundary edges of the xtal. How)

• consider_boundary_ends. (search behaves is decided by)

• consider_boundary_ends (If True, index of the xtal containing the)

• xtal's (selfpoint coordinates at one of the end points of its the)

• False (many boundary edges will be returned. If)

• be (the index will)

• completely (included only if the point is not on the end points but)

• points (inside the edge's end)

• is (provided that the cosider_boundary)

• True.

Return type:

List of indices of points which satisfy the condition.

Notes

To be developed.

split(method='byfactor', f=0.5, divider=None, saa=False, throw=True, update='pntb', perform_containment_check=True)

Split the self.line at location(s) specified.

Parameters:

• method (str) – Split specification mode. Supported values in current implementation are factor, p2d and coord.

• f (specifies the locations. Can be a numeric value or an iterable of) – numerical values. All values must be in the domain (0, 1).

• divider – Divider location used by p2d and coord modes.

• saa (bool) – If True, modifies current object and creates complementary segment.

• throw (bool) – If True, returns (self, new_line) after split.

• update (str) – Which endpoint of self is retained/updated (pnta or pntb).

• perform_containment_check (bool) – If True, validates divider is fully on and within self.

Returns:

(self, new_line) when throw=True and split succeeds.

Return type:

tuple

Examples

from upxo.geoEntities.sline2d import Sline2d as sl2d
from upxo.geoEntities.point2d import Point2d

line = sl2d(0, 0, 1, 0)
line.split(method='factor', f=0.75, saa=True, throw=True, update='pnta')

line = sl2d(0, 0, 1, 0)
line.split(method='factor', f=0.75, saa=True, throw=True, update='pntb')

line = sl2d(0, 0, 1, 0)
line.split(method='p2d', divider=Point2d(0.05, 0),
           saa=True, throw=True, update='pntb')

line = sl2d(0, 0, 1, 0)
line.split(method='p2d', divider=Point2d(0.05, 0),
           saa=True, throw=True, update='pnta')

line = sl2d(0, 0, 1, 0)
line.split(method='p2d', divider=Point2d(0.00, 0),
           saa=True, throw=True, update='pntb')

line = sl2d(0, 0, 1, 0)
line.split(method='coord', divider=(0.05, 0),
           saa=True, throw=True, update='pnta')

line = sl2d(0, 0, 1, 0)
line.split(method='coord', divider=(0.0, 0),
           saa=True, throw=True, update='pnta')