Geometry

Geometric primitives for 2D and 3D structural analysis.

Provides points, vectors, nodes, segments, edges, and polylines in 2D and 3D space, along with applied-vector and force-couple representations used throughout the PyCivil structural pipeline.

Typical units follow the PyCivil convention: millimetres (mm) for lengths, Newtons (N) for forces, and MPa for stresses.

Edge2d

A directed edge in a 2-D mesh connecting two Node2d instances.

Unlike Seg2d, an Edge2d carries node identifiers and is intended for use in mesh connectivity structures.

__init__(*args)

Initialise an Edge2d from exactly two Node2d arguments.

Parameters:

Name	Type	Description	Default
*args		Exactly two Node2d instances (node_i, node_j).	()

Raises:

Type	Description
TypeError	If the arguments are not two Node2d instances.

nodeI()

Return the start node of the edge.

Returns:

Name	Type	Description
Node2d	Node2d	Start node.

nodeJ()

Return the end node of the edge.

Returns:

Name	Type	Description
Node2d	Node2d	End node.

Edge3d

A directed edge in a 3-D mesh connecting two Node3d instances.

Supports three construction signatures:

• No arguments — creates an edge with two default (origin) nodes.
• Two Node3d instances — Edge3d(node_i, node_j).
• Eight numeric + id values — Edge3d(xi, yi, zi, idni, xj, yj, zj, idnj).

__init__(*args)

Initialise an Edge3d.

Parameters:

Name	Type	Description	Default
*args		One of the following signatures: () — default construction, both nodes at the origin. (Node3d, Node3d) — explicit node pair. (float, float, float, int, float, float, float, int) — coordinates and identifiers for node I followed by node J.	()

Raises:

Type	Description
Exception	On invalid argument types or counts.

lenght()

Return the length of the edge.

Returns:

Name	Type	Description
float	float	Euclidean distance between node I and node J.

nodeI()

Return the start node of the edge.

Returns:

Name	Type	Description
Node3d	Node3d	Start node.

nodeJ()

Return the end node of the edge.

Returns:

Name	Type	Description
Node3d	Node3d	End node.

setNodeI(*args)

Set the start node.

Parameters:

Name	Type	Description	Default
*args		Exactly one Node3d instance.	()

Raises:

Type	Description
Exception	If the argument is not a single Node3d.

setNodeJ(*args)

Set the end node.

Parameters:

Name	Type	Description	Default
*args		Exactly one Node3d instance.	()

Raises:

Type	Description
Exception	If the argument is not a single Node3d.

ForceCouple

A force-couple system (wrench) consisting of a resultant force and a moment.

Stores a force applied at a specific point together with a free couple vector. The couple is automatically updated when the application point is changed via the :attr:o setter (moment transport formula).

Attributes:

Name	Type	Description
force	Vector3dApp	Applied force as a Vector3dApp.
couple	Vector3d	Free moment vector as a Vector3d.

couple property writable

Vector3d: Deep copy of the free moment vector.

force property writable

Vector3dApp: Deep copy of the applied force.

o property writable

Point3d: Application point of the force (read from the force vector).

__add__(other)

Return the sum of two force-couples reduced to the same point.

The other force-couple is transported to self's application point before summing.

Parameters:

Name	Type	Description	Default
other	ForceCouple	The second ForceCouple.	required

Returns:

Name	Type	Description
ForceCouple	ForceCouple	Resultant force-couple at self's application point.

Raises:

Type	Description
ValueError	If other is not a ForceCouple.

__init__(force, couple)

Initialise a ForceCouple.

Deep copies are taken of both arguments to prevent external mutation.

Parameters:

Name	Type	Description	Default
force	Vector3dApp	The applied force (carries its application point).	required
couple	Vector3d	The free moment vector.	required

ForceCoupleSystem

A system of multiple ForceCouple objects.

Provides utilities to compute the barycentre of application points and to reduce the system to a single equivalent force-couple at a given point.

Note

This class is currently a stub — methods are not yet implemented.

__init__(forces)

Initialise a ForceCoupleSystem.

Parameters:

Name	Type	Description	Default
forces	List[ForceCouple]	List of ForceCouple objects forming the system.	required

baryOfApplicationPoints()

Return the barycentre of all force application points.

Returns:

Name	Type	Description
Point3d	Point3d	The barycentre point.

forceCoupleResume(applicationPoint)

Reduce the entire system to a single force-couple at applicationPoint.

Parameters:

Name	Type	Description	Default
applicationPoint	Point3d	The reference point for moment transport.	required

Returns:

Name	Type	Description
ForceCouple	ForceCouple	Equivalent resultant force-couple.

Node2d

Bases: Point2d

A 2-D mesh node extending Point2d with an integer identifier.

Attributes:

Name	Type	Description
idn		Integer node identifier (default -1 for unassigned).

__init__(x=0.0, y=0.0, idn=-1)

Initialise a Node2d.

Parameters:

Name	Type	Description	Default
x		X coordinate.	0.0
y		Y coordinate.	0.0
idn		Node identifier.	-1

Node3d

Bases: Point3d

A 3-D mesh node extending Point3d with an integer identifier.

Attributes:

Name	Type	Description
idn		Integer node identifier (default -1 for unassigned).

__init__(x=0.0, y=0.0, z=0.0, idn=-1)

Initialise a Node3d.

Parameters:

Name	Type	Description	Default
x		X coordinate.	0.0
y		Y coordinate.	0.0
z		Z coordinate.	0.0
idn		Node identifier.	-1

Point2d

A point (or free vector) in 2D Cartesian space.

Coordinates are stored as private attributes and exposed via properties. The class supports basic arithmetic (+, -, scalar *), equality testing, and common geometric operations such as rotation, translation, and signed-area calculation.

Attributes:

Name	Type	Description
x		X coordinate.
y		Y coordinate.

x property writable

float: X coordinate.

y property writable

float: Y coordinate.

__init__(x=0.0, y=0.0, make_null=False, coords=None)

Initialise a Point2d.

Parameters:

Name	Type	Description	Default
x	Union[float, int]	X coordinate. Ignored when coords is provided.	0.0
y	Union[float, int]	Y coordinate. Ignored when coords is provided.	0.0
make_null	bool	When True the point is flagged as a null sentinel (e.g. to signal a missing intersection result).	False
coords	Union[Tuple[Union[float, int], Union[float, int]], None]	Optional (x, y) tuple. Takes precedence over the individual x / y arguments when supplied.	None

Raises:

Type	Description
ValueError	If x is not a float or int.

affine(m11, m12, m21, m22, dx, dy)

Apply a general 2-D affine transformation in-place.

The transformation is defined as::

x' = m11*x + m12*y + dx
y' = m21*x + m22*y + dy

Parameters:

Name	Type	Description	Default
m11	float	Element (1,1) of the linear part.	required
m12	float	Element (1,2) of the linear part.	required
m21	float	Element (2,1) of the linear part.	required
m22	float	Element (2,2) of the linear part.	required
dx	float	Translation in X.	required
dy	float	Translation in Y.	required

Returns:

Name	Type	Description
Point2d	Point2d	self after the transformation (allows chaining).

areaFromTria(p0, p1, p2) staticmethod

Return the area of a triangle defined by three points.

Uses the standard cross-product (shoelace) formula.

Parameters:

Name	Type	Description	Default
p0	Point2d	First vertex.	required
p1	Point2d	Second vertex.	required
p2	Point2d	Third vertex.	required

Returns:

Name	Type	Description
float	float	Non-negative area of the triangle.

cross(p1, p2)

Compute the signed cross product (z-component) relative to this point.

Geometrically this equals twice the signed area of the triangle (self, p1, p2). A positive result means p2 is to the left of the directed edge self → p1.

Parameters:

Name	Type	Description	Default
p1	Point2d	First Point2d.	required
p2	Point2d	Second Point2d.	required

Returns:

Name	Type	Description
float	float	Signed cross product value.

distance(other)

Return the Euclidean distance to another point.

Parameters:

Name	Type	Description	Default
other	Point2d	Target Point2d.	required

Returns:

Name	Type	Description
float	float	Distance between the two points.

isEqualTo(other, rox, roy, prec)

Test approximate equality with reference scales and a tolerance.

The comparison is performed in normalised coordinates: each difference is divided by the corresponding reference length before checking against prec.

Parameters:

Name	Type	Description	Default
other		Another Point2d to compare against.	required
rox		Reference length along the X axis used for normalisation.	required
roy		Reference length along the Y axis used for normalisation.	required
prec		Tolerance threshold in normalised units.	required

Returns:

Name	Type	Description
bool		True if both normalised differences are smaller than prec.

isNull()

Return True if this point was created as a null sentinel.

Returns:

Name	Type	Description
bool	bool	True when the point carries no geometric meaning.

midpoint(other)

Return the midpoint between this point and other.

Parameters:

Name	Type	Description	Default
other	Point2d	The second Point2d.	required

Returns:

Name	Type	Description
Point2d	Point2d	The midpoint.

rotate(angle, center)

Rotate the point in-place around a given centre.

Parameters:

Name	Type	Description	Default
angle	float	Rotation angle in degrees (positive = counter-clockwise).	required
center	Point2d	Centre of rotation.	required

Returns:

Name	Type	Description
Point2d	Point2d	self after the rotation (allows chaining).

translate(dx, dy)

Translate the point in-place.

Parameters:

Name	Type	Description	Default
dx	float	Displacement along the X axis.	required
dy	float	Displacement along the Y axis.	required

Returns:

Name	Type	Description
Point2d	Point2d	self after the translation (allows chaining).

Point2dMdl

Bases: BaseModel

Pydantic model wrapping an optional 2-D point coordinate pair.

Attributes:

Name	Type	Description
xy	Optional[Tuple[float, float]]	Optional (x, y) coordinate tuple.

Point3d

A point (or free vector) in 3D Cartesian space.

Attributes:

Name	Type	Description
x		X coordinate.
y		Y coordinate.
z		Z coordinate.

x property writable

float: X coordinate.

y property writable

float: Y coordinate.

z property writable

float: Z coordinate.

__init__(x=0.0, y=0.0, z=0.0)

Initialise a Point3d.

Parameters:

Name	Type	Description	Default
x		X coordinate.	0.0
y		Y coordinate.	0.0
z		Z coordinate.	0.0

distanceFrom(p)

Return the Euclidean distance to another 3-D point.

Parameters:

Name	Type	Description	Default
p	Point3d	Target Point3d.	required

Returns:

Name	Type	Description
float	float	Distance between the two points.

Raises:

Type	Description
Exception	If p is not a Point3d instance.

midpoint(other)

Return the midpoint between this point and other.

Parameters:

Name	Type	Description	Default
other	Point3d	The second Point2d.	required

Returns:

Name	Type	Description
Point3d	Point3d	The midpoint.

tranlate(dx=0.0, dy=0.0, dz=0.0)

Translate the point in-place.

Parameters:

Name	Type	Description	Default
dx		Displacement along the X axis.	0.0
dy		Displacement along the Y axis.	0.0
dz		Displacement along the Z axis.	0.0

Polyline2d

List of Nodes2D

An ordered sequence of Node2d vertices representing an open or closed 2-D polyline (polygon boundary).

__init__(*args)

Initialise a Polyline2d from a list of nodes.

Parameters:

Name	Type	Description	Default
*args		Exactly one positional argument — a list of Node2d instances.	()

Raises:

Type	Description
TypeError	If the argument count is wrong, the argument is not a list, or any list element is not a Node2d.

getNodes()

Return the underlying list of nodes.

Returns:

Type	Description
list[Node2d]	list[Node2d]: The node list (not a copy).

isClosed()

Return True if the first and last nodes are the same.

Returns:

Name	Type	Description
bool	bool	True when the polyline is closed.

setClosed()

Close the polyline by appending the first node at the end.

size()

Return the number of nodes in the polyline.

Returns:

Name	Type	Description
int	int	Node count.

translate(pStart, pEnd)

Translate all nodes by the vector pEnd - pStart.

Parameters:

Name	Type	Description	Default
pStart	Union[Point2d, None]	Origin of the translation vector. Defaults to the coordinate origin when None.	required
pEnd	Union[Point2d, None]	Tip of the translation vector. Defaults to the coordinate origin when None.	required

vertexAt(i)

Return the number of sub-vertices at position i.

Parameters:

Name	Type	Description	Default
i		Index into the node list.	required

Returns:

Name	Type	Description
int		Length of the node at position i (typically always 1 for plain Node2d objects).

vertexNb()

Return the number of vertices in the polyline.

Returns:

Name	Type	Description
int	int	Vertex count (alias for :meth:size).

Polyline3d

List of Nodes3D

An ordered sequence of Node3d vertices representing an open or closed 3-D polyline.

__init__(*args)

Initialise a Polyline3d from a list of nodes.

Parameters:

Name	Type	Description	Default
*args		Exactly one positional argument — a list of Node3d instances.	()

Raises:

Type	Description
Exception	If the argument count is wrong, the argument is not a list, or any list element is not a Node3d.

isClosed()

Return True if the first and last nodes are the same.

Returns:

Name	Type	Description
bool	bool	True when the polyline is closed.

setClosed()

Close the polyline by appending the first node at the end.

vertexAt(i)

Return the number of sub-vertices at position i.

Parameters:

Name	Type	Description	Default
i		Index into the node list.	required

Returns:

Name	Type	Description
int		Length of the node at position i.

vertexNb()

Return the number of vertices in the polyline.

Returns:

Name	Type	Description
int	int	Vertex count.

Seg2d

A directed line segment in 2-D space defined by two Point2d endpoints.

Provides intersection, containment, and factor utilities needed for polygon clipping and section outline processing.

Attributes:

Name	Type	Description
p0		Start point of the segment.
p1		End point of the segment.

p0 property writable

Point2d: Start point.

p1 property writable

Point2d: End point.

__init__(p0, p1)

Initialise a Seg2d from two endpoints.

Parameters:

Name	Type	Description	Default
p0	Point2d	Start point.	required
p1	Point2d	End point.	required

boundingHasPoint(p, toll=1e-15)

Test whether p lies within the axis-aligned bounding box of this segment.

Parameters:

Name	Type	Description	Default
p	Point2d	The point to test.	required
toll	float	Absolute tolerance added to the bounding box extents.	1e-15

Returns:

Name	Type	Description
bool	bool	True if p is inside (or on) the expanded bounding box.

extensionFactor(p)

Compute the scalar factor such that factor * self == p.

Useful for parametric position queries along the infinite line through self. The Y component is preferred when the X component of the segment direction is zero.

Parameters:

Name	Type	Description	Default
p	Point2d	Target Point2d.	required

Returns:

Name	Type	Description
float	float	Extension factor along the segment direction.

intersect(other)

Return the intersection point of the two infinite lines.

The lines are the infinite extensions of self and other. If the lines are parallel (determinant == 0) a null Point2d is returned.

Parameters:

Name	Type	Description	Default
other	Seg2d	The second segment (treated as an infinite line).	required

Returns:

Name	Type	Description
Point2d	Point2d	Intersection point, or a null Point2d if parallel.

intersectAndContaints(other)

Intersect two segments and report whether the intersection lies on self.

Uses a length-ratio test: the intersection belongs to self when the sum of its distances to p0 and p1 equals the segment length (within numerical tolerance).

Parameters:

Name	Type	Description	Default
other	Seg2d	The second segment.	required

Returns:

Type	Description
Tuple[bool, Point2d]	Tuple[bool, Point2d]: A (contained, point) pair where contained is True if the intersection point lies on self, and point is the intersection Point2d.

len()

Return the length of the segment.

Returns:

Name	Type	Description
float	float	Euclidean distance between p0 and p1.

Vector2d

A free vector in 2-D space.

Can be constructed either from two Point2d endpoints or by providing the components directly.

Attributes:

Name	Type	Description
vx		X component.
vy		Y component.

__init__(p0=Point2d(make_null=True), p1=Point2d(make_null=True), vx=0.0, vy=0.0)

Initialise a Vector2d.

When p0 and p1 are non-null Point2d instances the vector is set to p1 - p0. Otherwise vx / vy are used directly.

Parameters:

Name	Type	Description	Default
p0	Point2d	Start point (optional).	Point2d(make_null=True)
p1	Point2d	End point (optional).	Point2d(make_null=True)
vx	float	X component used when p0 / p1 are null.	0.0
vy	float	Y component used when p0 / p1 are null.	0.0

Raises:

Type	Description
TypeError	If p0 or p1 are not Point2d instances.

cross(other)

Compute the scalar cross product (z-component of 3-D cross).

Parameters:

Name	Type	Description	Default
other	Vector2d	The second Vector2d.	required

Returns:

Name	Type	Description
float	float	vx * other.vy - other.vx * vy.

norm()

Return the Euclidean norm of the vector.

Returns:

Name	Type	Description
float	float	sqrt(vx² + vy²).

norm_roxroy(rox=1.0, roy=1.0)

Return the norm scaled by reference lengths along each axis.

Parameters:

Name	Type	Description	Default
rox	float	Reference length for the X component.	1.0
roy	float	Reference length for the Y component.	1.0

Returns:

Name	Type	Description
float	float	sqrt((vx/rox)² + (vy/roy)²).

normalize()

Normalise the vector in-place to unit length.

Returns:

Name	Type	Description
Vector2d	Vector2d	self after normalisation (allows chaining).

Raises:

Type	Description
Exception	If the vector is the zero vector.

rotate(angle)

Rotate the vector in-place around the origin.

Parameters:

Name	Type	Description	Default
angle	float	Rotation angle in degrees (positive = counter-clockwise).	required

Returns:

Name	Type	Description
Vector2d	Vector2d	self after rotation (allows chaining).

Vector3d

A free vector in 3-D space.

Supports multiple construction signatures:

• No arguments — zero vector.
• Three scalars — Vector3d(vx, vy, vz).
• Two Point3d instances — Vector3d(p0, p1) → p1 - p0.
• One 3-tuple of scalars — Vector3d((vx, vy, vz)).

Attributes:

Name	Type	Description
vx		X component.
vy		Y component.
vz		Z component.

__init__(*args)

Initialise a Vector3d.

Parameters:

Name	Type	Description	Default
*args		One of the supported signatures described in the class docstring.	()

Raises:

Type	Description
Exception	On unsupported argument types or counts.

cross(other)

Return the 3-D cross product self × other.

Parameters:

Name	Type	Description	Default
other	Vector3d	The second Vector3d.	required

Returns:

Name	Type	Description
Vector3d	Vector3d	A new vector orthogonal to both operands.

norm()

Return the Euclidean norm of the vector.

Returns:

Name	Type	Description
float	float	sqrt(vx² + vy² + vz²).

normalize()

Normalise the vector in-place to unit length.

Returns:

Name	Type	Description
Vector3d	Vector3d	self after normalisation (allows chaining).

Raises:

Type	Description
Exception	If the vector is the zero vector.

rotate(angle, axis)

Rotate the vector in-place around the origin with Rodriguez formula.

Rodriguez, say that if V is original vector, theta angle and K unit vector, we rotated vetor will be:

Vrot = Vcos(theta) + (K cross V)*sin(theta) + K(K scalar V)(1 - cos(theta))

Parameters:

Name	Type	Description	Default
angle	float	Rotation angle in degrees (positive = counter-clockwise).	required
axis	Vector3d	Axis of rotation. Can be also not normalized but not null	required

Returns:

Name	Type	Description
Vector2d	Vector3d	self after rotation (allows chaining).

scalar(other)

Return the dot product of this vector with other.

Parameters:

Name	Type	Description	Default
other	Vector3d	The second Vector3d.	required

Returns:

Name	Type	Description
float	float	vx*other.vx + vy*other.vy + vz*other.vz.

Vector3dApp

Bases: Vector3d

A 3-D vector with an explicit application point (origin).

Extends Vector3d by storing the point in space where the vector is applied, which is required for moment transport and force-couple operations.

Attributes:

Name	Type	Description
o	Point3d	Application point (Point3d).

o property writable

Point3d: Application point of the vector.

__init__(origin, *args)

Initialise a Vector3dApp.

Parameters:

Name	Type	Description	Default
origin	Point3d	The application point of the vector.	required
*args	float | int | tuple[float | int, float | int, float | int]	Vector components forwarded to the Vector3d constructor (three scalars, a 3-tuple, or nothing for the zero vector).	()

affineSum2d(p, v)

Return the point obtained by adding a 2-D vector to a point.

Parameters:

Name	Type	Description	Default
p	Point2d	Base point.	required
v	Vector2d	Displacement vector.	required

Returns:

Name	Type	Description
Point2d	Point2d	p + v.

areaFromTria3D(p0, p1, p2)

Return the area of a 3-D triangle defined by three points.

Uses the cross-product formula: area = 0.5 * |v × w| where v = p0→p1 and w = p1→p2.

Parameters:

Name	Type	Description	Default
p0	Point3d	First vertex.	required
p1	Point3d	Second vertex.	required
p2	Point3d	Third vertex.	required

Returns:

Name	Type	Description
float	float	Non-negative area of the triangle.

boundingBox(p1, p2)

Return the axis-aligned bounding box of two 2-D points.

Parameters:

Name	Type	Description	Default
p1		First Point2d.	required
p2		Second Point2d.	required

Returns:

Type	Description
	list[float]: [min_x, max_x, min_y, max_y].

Raises:

Type	Description
Exception	If either argument is not a Point2d.

twoPointsDivide(p0, p1, nb, extremes=True)

Divide the segment p0 → p1 into nb equal parts.

Parameters:

Name	Type	Description	Default
p0	Point2d	Start point.	required
p1	Point2d	End point.	required
nb	int	Number of equal sub-divisions (must be ≥ 1).	required
extremes	bool	When True (default), p0 and p1 are included as the first and last points of the result.	True

Returns:

Type	Description
List[Point2d]	List[Point2d]: Points along the segment at equal spacing.

Raises:

Type	Description
ValueError	If nb < 1.

twoPointsMiddle(p0, p1)

Return the midpoint between two 2-D points.

Parameters:

Name	Type	Description	Default
p0	Point2d	First point.	required
p1	Point2d	Second point.	required

Returns:

Name	Type	Description
Point2d	Point2d	The midpoint (p0 + p1) / 2.

twoPointsOffset(p0, p1, offset=0.0)

Return copies of p0 and p1 offset perpendicularly by offset.

The normal direction is obtained by rotating the segment direction 90° counter-clockwise.

Parameters:

Name	Type	Description	Default
p0	Point2d	Start point of the reference segment.	required
p1	Point2d	End point of the reference segment.	required
offset	float	Lateral offset distance (positive = left of p0→p1).	0.0

Returns:

Type	Description
Tuple[Point2d, Point2d]	Tuple[Point2d, Point2d]: The offset copies (p0', p1').