Utility functions and classes located in module ezdxf.math
.
Functions¶
-
ezdxf.math.
is_close_points
(p1: Vertex, p2: Vertex, abs_tol=1e-10) → bool¶ Returns
True
if p1 is very close to p2.
-
ezdxf.math.
closest_point
(base: Vertex, points: Iterable[Vertex]) → Vector¶ Returns closest point to base.
-
ezdxf.math.
uniform_knot_vector
(count: int, order: int, normalize=False) → List[float]¶ Returns an uniform knot vector for a B-spline of order and count control points.
order = degree + 1
- Parameters
count – count of control points
order – spline order
normalize – normalize values in range [0, 1] if
True
-
ezdxf.math.
open_uniform_knot_vector
(count: int, order: int, normalize=False) → List[float]¶ Returns an open (clamped) uniform knot vector for a B-spline of order and count control points.
order = degree + 1
- Parameters
count – count of control points
order – spline order
normalize – normalize values in range [0, 1] if
True
-
ezdxf.math.
required_knot_values
(count: int, order: int) → int¶ Returns the count of required knot values for a B-spline of order and count control points.
- Parameters
count – count of control points, in text-books referred as “n + 1”
order – order of B-Spline, in text-books referred as “k”
Relationship:
“p” is the degree of the B-spline, text-book notation.
k = p + 1
2 ≤ k ≤ n + 1
-
ezdxf.math.
xround
(value: float, rounding: float = 0.0) → float¶ Extended rounding function, argument rounding defines the rounding limit:
0
remove fraction
0.1
round next to x.1, x.2, … x.0
0.25
round next to x.25, x.50, x.75 or x.00
0.5
round next to x.5 or x.0
1.0
round to a multiple of 1: remove fraction
2.0
round to a multiple of 2: xxx2, xxx4, xxx6 …
5.0
round to a multiple of 5: xxx5 or xxx0
10.0
round to a multiple of 10: xx10, xx20, …
- Parameters
value – float value to round
rounding – rounding limit
-
ezdxf.math.
linspace
(start: float, stop: float, num: int, endpoint=True) → Iterable[float]¶ Return evenly spaced numbers over a specified interval, like numpy.linspace().
Returns num evenly spaced samples, calculated over the interval [start, stop]. The endpoint of the interval can optionally be excluded.
New in version 0.12.3.
2D Functions¶
-
ezdxf.math.
arc_segment_count
(radius: float, angle: float, sagitta: float) → int¶ Returns the count of required segments for the approximation of an arc for a given maximum sagitta.
- Parameters
radius – arc radius
angle – angle span of the arc in radians
sagitta – max. distance from the center of the arc to the center of its base
New in version 0.14.
-
ezdxf.math.
arc_chord_length
(radius: float, sagitta: float) → float¶ Returns the chord length for an arc defined by radius and the sagitta.
- Parameters
radius – arc radius
sagitta – distance from the center of the arc to the center of its base
New in version 0.14.
-
ezdxf.math.
distance_point_line_2d
(point: Vec2, start: Vec2, end: Vec2) → float¶ Returns distance from point to line defined by start- and end point.
-
ezdxf.math.
point_to_line_relation
(point: Vec2, start: Vec2, end: Vec2, abs_tol=1e-10) → int¶ Returns
-1
if point is left line,+1
if point is right of line and0
if point is on the line. The line is defined by two vertices given as arguments start and end.
-
ezdxf.math.
is_point_on_line_2d
(point: Vec2, start: Vec2, end: Vec2, ray=True, abs_tol=1e-10) → bool¶ Returns
True
if point is on line.
-
ezdxf.math.
is_point_left_of_line
(point: Vec2, start: Vec2, end: Vec2, colinear=False) → bool¶ Returns
True
if point is “left of line” defined by start- and end point, a colinear point is also “left of line” if argument colinear isTrue
.
-
ezdxf.math.
is_point_in_polygon_2d
(point: Vec2, polygon: Iterable[Vec2], abs_tol=1e-10) → int¶ Test if point is inside polygon.
- Parameters
- Returns
+1
for inside,0
for on boundary line,-1
for outside
New in version 0.11.
-
ezdxf.math.
convex_hull_2d
(points: Iterable[Vertex]) → List[Vertex]¶ Returns 2D convex hull for points.
- Parameters
points – iterable of points as
Vector
compatible objects, z-axis is ignored
-
ezdxf.math.
intersection_line_line_2d
(line1: Sequence[Vec2], line2: Sequence[Vec2], virtual=True, abs_tol=1e-10) → Optional[Vec2]¶ Compute the intersection of two lines in the xy-plane.
- Parameters
line1 – start- and end point of first line to test e.g. ((x1, y1), (x2, y2)).
line2 – start- and end point of second line to test e.g. ((x3, y3), (x4, y4)).
virtual –
True
returns any intersection point,False
returns only real intersection points.abs_tol – tolerance for intersection test.
- Returns
None
if there is no intersection point (parallel lines) or intersection point asVec2
-
ezdxf.math.
rytz_axis_construction
(d1: Vector, d2: Vector) → Tuple[Vector, Vector, float]¶ The Rytz’s axis construction is a basic method of descriptive Geometry to find the axes, the semi-major axis and semi-minor axis, starting from two conjugated half-diameters.
Source: Wikipedia
Given conjugated diameter d1 is the vector from center C to point P and the given conjugated diameter d2 is the vector from center C to point Q. Center of ellipse is always
(0, 0, 0)
. This algorithm works for 2D/3D vectors.
-
ezdxf.math.
offset_vertices_2d
(vertices: Iterable[Vertex], offset: float, closed: bool = False) → Iterable[Vec2]¶ Yields vertices of the offset line to the shape defined by vertices. The source shape consist of straight segments and is located in the xy-plane, the z-axis of input vertices is ignored. Takes closed shapes into account if argument closed is
True
, which yields intersection of first and last offset segment as first vertex for a closed shape. For closed shapes the first and last vertex can be equal, else an implicit closing segment from last to first vertex is added. A shape with equal first and last vertex is not handled automatically as closed shape.Warning
Adjacent collinear segments in opposite directions, same as a turn by 180 degree (U-turn), leads to unexpected results.
New in version 0.11.
- Parameters
vertices – source shape defined by vertices
offset – line offset perpendicular to direction of shape segments defined by vertices order, offset >
0
is ‘left’ of line segment, offset <0
is ‘right’ of line segmentclosed –
True
to handle as closed shape
source = [(0, 0), (3, 0), (3, 3), (0, 3)]
result = list(offset_vertices_2d(source, offset=0.5, closed=True))

Example for a closed collinear shape, which creates 2 additional vertices and the first one has an unexpected location:
source = [(0, 0), (0, 1), (0, 2), (0, 3)]
result = list(offset_vertices_2d(source, offset=0.5, closed=True))

3D Functions¶
-
ezdxf.math.
normal_vector_3p
(a: Vector, b: Vector, c: Vector) → Vector¶ Returns normal vector for 3 points, which is the normalized cross product for:
a->b x a->c
.New in version 0.11.
-
ezdxf.math.
is_planar_face
(face: Sequence[Vector], abs_tol=1e-9) → bool¶ Returns
True
if sequence of vectors is a planar face.- Parameters
face – sequence of
Vector
objectsabs_tol – tolerance for normals check
New in version 0.11.
-
ezdxf.math.
subdivide_face
(face: Sequence[Union[Vector, Vec2]], quads=True) → Iterable[List[Vector]]¶ Yields new subdivided faces. Creates new faces from subdivided edges and the face midpoint by linear interpolation.
- Parameters
New in version 0.11.
-
ezdxf.math.
subdivide_ngons
(faces: Iterable[Sequence[Union[Vector, Vec2]]]) → Iterable[List[Vector]]¶ Yields only triangles or quad faces, subdivides ngons into triangles.
New in version 0.12.
-
ezdxf.math.
intersection_ray_ray_3d
(ray1: Tuple[Vector, Vector], ray2: Tuple[Vector, Vector], abs_tol=1e-10) → Sequence[Vector]¶ Calculate intersection of two rays, returns a 0-tuple for parallel rays, a 1-tuple for intersecting rays and a 2-tuple for not intersecting and not parallel rays with points of closest approach on each ray.
- Parameters
New in version 0.11.
-
ezdxf.math.
estimate_tangents
(points: List[Vector], method: str = '5-points', normalize=True) → List[Vector]¶ Estimate tangents for curve defined by given fit points. Calculated tangents are normalized (unit-vectors).
Available tangent estimation methods:
“3-points”: 3 point interpolation
“5-points”: 5 point interpolation
“bezier”: tangents from an interpolated cubic bezier curve
“diff”: finite difference
- Parameters
points – start-, end- and passing points of curve
method – tangent estimation method
normalize – normalize tangents if
True
- Returns
tangents as list of
Vector
objects
-
ezdxf.math.
estimate_end_tangent_magnitude
(points: List[Vector], method: str = 'chord') → List[Vector]¶ Estimate tangent magnitude of start- and end tangents.
Available estimation methods:
“chord”: total chord length, curve approximation by straight segments
“arc”: total arc length, curve approximation by arcs
“bezier-n”: total length from cubic bezier curve approximation, n segments per section
- Parameters
points – start-, end- and passing points of curve
method – tangent magnitude estimation method
-
ezdxf.math.
fit_points_to_cad_cv
(fit_points: Iterable[Vertex], degree: int = 3, method='chord', tangents: Iterable[Vertex] = None) → BSpline¶ Returns the control vertices and knot vector configuration for DXF SPLINE entities defined only by fit points as close as possible to common CAD applications like BricsCAD.
There exist infinite numerical correct solution for this setup, but some facts are known:
Global curve interpolation with start- and end derivatives, e.g. 6 fit points creates 8 control vertices in BricsCAD
Degree of B-spline is limited to 2 or 3, a stored degree of >3 is ignored, this limit exist only for B-splines defined by fit points
Knot parametrization method is “chord”
Knot distribution is “natural”
The last missing parameter is the start- and end tangents estimation method used by BricsCAD, if these tangents are stored in the DXF file provide them as argument tangents as 2-tuple (start, end) and the interpolated control vertices will match the BricsCAD calculation, except for floating point imprecision.
- Parameters
fit_points – points the spline is passing through
degree – degree of spline, only 2 or 3 is supported by BricsCAD, default = 3
method – knot parametrization method, default = ‘chord’
tangents – start- and end tangent, default is autodetect
- Returns
New in version 0.13.
-
ezdxf.math.
global_bspline_interpolation
(fit_points: Iterable[Vertex], degree: int = 3, tangents: Iterable[Vertex] = None, method: str = 'chord') → BSpline¶ B-spline interpolation by Global Curve Interpolation. Given are the fit points and the degree of the B-spline. The function provides 3 methods for generating the parameter vector t:
“uniform”: creates a uniform t vector, from 0 to 1 evenly spaced, see uniform method
“chord”, “distance”: creates a t vector with values proportional to the fit point distances, see chord length method
“centripetal”, “sqrt_chord”: creates a t vector with values proportional to the fit point sqrt(distances), see centripetal method
“arc”: creates a t vector with values proportional to the arc length between fit points.
It is possible to constraint the curve by tangents, by start- and end tangent if only two tangents are given or by one tangent for each fit point.
If tangents are given, they represent 1st derivatives and and should be scaled if they are unit vectors, if only start- and end tangents given the function
estimate_end_tangent_magnitude()
helps with an educated guess, if all tangents are given, scaling by chord length is a reasonable choice (Piegl & Tiller).- Parameters
fit_points – fit points of B-spline, as list of
Vector
compatible objectstangents – if only two vectors are given, take the first and the last vector as start- and end tangent constraints or if for all fit points a tangent is given use all tangents as interpolation constraints (optional)
degree – degree of B-spline
method – calculation method for parameter vector t
- Returns
-
ezdxf.math.
local_cubic_bspline_interpolation
(fit_points: Iterable[Vertex], method: str = '5-points', tangents: Iterable[Vertex] = None) → BSpline¶ B-spline interpolation by ‘Local Cubic Curve Interpolation’, which creates B-spline from fit points and estimated tangent direction at start-, end- and passing points.
Source: Piegl & Tiller: “The NURBS Book” - chapter 9.3.4
Available tangent estimation methods:
“3-points”: 3 point interpolation
“5-points”: 5 point interpolation
“bezier”: cubic bezier curve interpolation
“diff”: finite difference
or pass pre-calculated tangents, which overrides tangent estimation.
-
ezdxf.math.
rational_spline_from_arc
(center: Vector = (0, 0), radius: float = 1, start_angle: float = 0, end_angle: float = 360, segments: int = 1) → BSpline¶ Returns a rational B-splines for a circular 2D arc.
- Parameters
center – circle center as
Vector
compatible objectradius – circle radius
start_angle – start angle in degrees
end_angle – end angle in degrees
segments – count of spline segments, at least one segment for each quarter (90 deg),
1
for as few as needed.
New in version 0.13.
-
ezdxf.math.
rational_spline_from_ellipse
(ellipse: ConstructionEllipse, segments: int = 1) → BSpline¶ Returns a rational B-splines for an elliptic arc.
- Parameters
ellipse – ellipse parameters as
ConstructionEllipse
objectsegments – count of spline segments, at least one segment for each quarter (pi/2),
1
for as few as needed.
New in version 0.13.
-
ezdxf.math.
cubic_bezier_from_arc
(center: Vector = (0, 0), radius: float = 1, start_angle: float = 0, end_angle: float = 360, segments: int = 1) → Iterable[Bezier4P]¶ Returns an approximation for a circular 2D arc by multiple cubic Bézier-curves.
- Parameters
center – circle center as
Vector
compatible objectradius – circle radius
start_angle – start angle in degrees
end_angle – end angle in degrees
segments – count of Bèzier-curve segments, at least one segment for each quarter (90 deg),
1
for as few as possible.
New in version 0.13.
-
ezdxf.math.
cubic_bezier_from_ellipse
(ellipse: ConstructionEllipse, segments: int = 1) → Iterable[Bezier4P]¶ Returns an approximation for an elliptic arc by multiple cubic Bézier-curves.
- Parameters
ellipse – ellipse parameters as
ConstructionEllipse
objectsegments – count of Bèzier-curve segments, at least one segment for each quarter (pi/2),
for as few as possible. (1) –
New in version 0.13.
-
ezdxf.math.
cubic_bezier_interpolation
(points: Iterable[Vertex]) → List[Bezier4P]¶ Returns an interpolation curve for given data points as multiple cubic Bézier-curves. Returns n-1 cubic Bézier-curves for n given data points, curve i goes from point[i] to point[i+1].
- Parameters
points – data points
New in version 0.13.
Transformation Classes¶
OCS Class¶
-
class
ezdxf.math.
OCS
(extrusion: Vertex = Vector(0.0, 0.0, 1.0))¶ Establish an OCS for a given extrusion vector.
- Parameters
extrusion – extrusion vector.
-
ux
¶ x-axis unit vector
-
uy
¶ y-axis unit vector
-
uz
¶ z-axis unit vector
-
from_wcs
(point: Vertex) → Vertex¶ Returns OCS vector for WCS point.
-
points_from_wcs
(points: Iterable[Vertex]) → Iterable[Vertex]¶ Returns iterable of OCS vectors from WCS points.
-
to_wcs
(point: Vertex) → Vertex¶ Returns WCS vector for OCS point.
-
points_to_wcs
(points: Iterable[Vertex]) → Iterable[Vertex]¶ Returns iterable of WCS vectors for OCS points.
-
render_axis
(layout: BaseLayout, length: float = 1, colors: Tuple[int, int, int] = (1, 3, 5))¶ Render axis as 3D lines into a layout.
UCS Class¶
-
class
ezdxf.math.
UCS
(origin: Vertex = (0, 0, 0), ux: Vertex = None, uy: Vertex = None, uz: Vertex = None)¶ Establish an user coordinate system (UCS). The UCS is defined by the origin and two unit vectors for the x-, y- or z-axis, all axis in WCS. The missing axis is the cross product of the given axis.
If x- and y-axis are
None
: ux =(1, 0, 0)
, uy =(0, 1, 0)
, uz =(0, 0, 1)
.Unit vectors don’t have to be normalized, normalization is done at initialization, this is also the reason why scaling gets lost by copying or rotating.
- Parameters
-
ux
¶ x-axis unit vector
-
uy
¶ y-axis unit vector
-
uz
¶ z-axis unit vector
-
is_cartesian
¶ Returns
True
if cartesian coordinate system.
-
points_to_wcs
(points: Iterable[Vertex]) → Iterable[Vector]¶ Returns iterable of WCS vectors for UCS points.
-
direction_to_wcs
(vector: Vertex) → Vector¶ Returns WCS direction for UCS vector without origin adjustment.
-
points_from_wcs
(points: Iterable[Vertex]) → Iterable[Vector]¶ Returns iterable of UCS vectors from WCS points.
-
direction_from_wcs
(vector: Vertex) → Vector¶ Returns UCS vector for WCS vector without origin adjustment.
-
points_to_ocs
(points: Iterable[Vertex]) → Iterable[Vector]¶ Returns iterable of OCS vectors for UCS points.
The
OCS
is defined by the z-axis of theUCS
.- Parameters
points – iterable of UCS vertices
-
to_ocs_angle_deg
(angle: float) → float¶ Transforms angle from current UCS to the parent coordinate system (most likely the WCS) including the transformation to the OCS established by the extrusion vector
UCS.uz
.- Parameters
angle – in UCS in degrees
-
transform
(m: Matrix44) → UCS¶ General inplace transformation interface, returns self (floating interface).
- Parameters
m – 4x4 transformation matrix (
ezdxf.math.Matrix44
)
New in version 0.14.
-
rotate
(axis: Vertex, angle: float) → UCS¶ Returns a new rotated UCS, with the same origin as the source UCS. The rotation vector is located in the origin and has WCS coordinates e.g. (0, 0, 1) is the WCS z-axis as rotation vector.
New in version 0.11.
- Parameters
axis – arbitrary rotation axis as vector in WCS
angle – rotation angle in radians
-
rotate_local_x
(angle: float) → UCS¶ Returns a new rotated UCS, rotation axis is the local x-axis.
New in version 0.11.
- Parameters
angle – rotation angle in radians
-
rotate_local_y
(angle: float) → UCS¶ Returns a new rotated UCS, rotation axis is the local y-axis.
New in version 0.11.
- Parameters
angle – rotation angle in radians
-
rotate_local_z
(angle: float) → UCS¶ Returns a new rotated UCS, rotation axis is the local z-axis.
New in version 0.11.
- Parameters
angle – rotation angle in radians
-
shift
(delta: Vertex) → UCS¶ Shifts current UCS by delta vector and returns self.
New in version 0.11.
- Parameters
delta – shifting vector
-
moveto
(location: Vertex) → UCS¶ Place current UCS at new origin location and returns self.
New in version 0.11.
- Parameters
location – new origin in WCS
-
static
from_x_axis_and_point_in_xy
(origin: Vertex, axis: Vertex, point: Vertex) → UCS¶ Returns an new
UCS
defined by the origin, the x-axis vector and an arbitrary point in the xy-plane.
-
static
from_x_axis_and_point_in_xz
(origin: Vertex, axis: Vertex, point: Vertex) → UCS¶ Returns an new
UCS
defined by the origin, the x-axis vector and an arbitrary point in the xz-plane.
-
static
from_y_axis_and_point_in_xy
(origin: Vertex, axis: Vertex, point: Vertex) → UCS¶ Returns an new
UCS
defined by the origin, the y-axis vector and an arbitrary point in the xy-plane.
-
static
from_y_axis_and_point_in_yz
(origin: Vertex, axis: Vertex, point: Vertex) → UCS¶ Returns an new
UCS
defined by the origin, the y-axis vector and an arbitrary point in the yz-plane.
-
static
from_z_axis_and_point_in_xz
(origin: Vertex, axis: Vertex, point: Vertex) → UCS¶ Returns an new
UCS
defined by the origin, the z-axis vector and an arbitrary point in the xz-plane.
-
static
from_z_axis_and_point_in_yz
(origin: Vertex, axis: Vertex, point: Vertex) → UCS¶ Returns an new
UCS
defined by the origin, the z-axis vector and an arbitrary point in the yz-plane.
-
render_axis
(layout: BaseLayout, length: float = 1, colors: Tuple[int, int, int] = (1, 3, 5))¶ Render axis as 3D lines into a layout.
Matrix44¶
-
class
ezdxf.math.
Matrix44
(*args)¶ This is a pure Python implementation for 4x4 transformation matrices, to avoid dependency to big numerical packages like
numpy
, before binary wheels, installation of these packages wasn’t always easy on Windows.The utility functions for constructing transformations and transforming vectors and points assumes that vectors are stored as row vectors, meaning when multiplied, transformations are applied left to right (e.g. vAB transforms v by A then by B).
Matrix44 initialization:
Matrix44()
returns the identity matrix.Matrix44(values)
values is an iterable with the 16 components of the matrix.Matrix44(row1, row2, row3, row4)
four rows, each row with four values.
-
__repr__
() → str¶ Returns the representation string of the matrix:
Matrix44((col0, col1, col2, col3), (...), (...), (...))
-
set
(*args) → None¶ Set matrix values.
set()
creates the identity matrix.set(values)
values is an iterable with the 16 components of the matrix.set(row1, row2, row3, row4)
four rows, each row with four values.
-
get_row
(row: int) → Tuple[float, …]¶ Get row as list of of four float values.
- Parameters
row – row index [0 .. 3]
-
set_row
(row: int, values: Sequence[float]) → None¶ Sets the values in a row.
- Parameters
row – row index [0 .. 3]
values – iterable of four row values
-
get_col
(col: int) → Tuple[float, …]¶ Returns a column as a tuple of four floats.
- Parameters
col – column index [0 .. 3]
-
set_col
(col: int, values: Sequence[float])¶ Sets the values in a column.
- Parameters
col – column index [0 .. 3]
values – iterable of four column values
-
classmethod
scale
(sx: float, sy: float = None, sz: float = None) → Matrix44¶ Returns a scaling transformation matrix. If sy is
None
, sy = sx, and if sz isNone
sz = sx.
-
classmethod
translate
(dx: float, dy: float, dz: float) → Matrix44¶ Returns a translation matrix for translation vector (dx, dy, dz).
-
classmethod
x_rotate
(angle: float) → Matrix44¶ Returns a rotation matrix about the x-axis.
- Parameters
angle – rotation angle in radians
-
classmethod
y_rotate
(angle: float) → Matrix44¶ Returns a rotation matrix about the y-axis.
- Parameters
angle – rotation angle in radians
-
classmethod
z_rotate
(angle: float) → Matrix44¶ Returns a rotation matrix about the z-axis.
- Parameters
angle – rotation angle in radians
-
classmethod
axis_rotate
(axis: Vertex, angle: float) → Matrix44¶ Returns a rotation matrix about an arbitrary axis.
- Parameters
axis – rotation axis as
(x, y, z)
tuple orVector
objectangle – rotation angle in radians
-
classmethod
xyz_rotate
(angle_x: float, angle_y: float, angle_z: float) → Matrix44¶ Returns a rotation matrix for rotation about each axis.
- Parameters
angle_x – rotation angle about x-axis in radians
angle_y – rotation angle about y-axis in radians
angle_z – rotation angle about z-axis in radians
-
classmethod
perspective_projection
(left: float, right: float, top: float, bottom: float, near: float, far: float) → Matrix44¶ Returns a matrix for a 2D projection.
- Parameters
left – Coordinate of left of screen
right – Coordinate of right of screen
top – Coordinate of the top of the screen
bottom – Coordinate of the bottom of the screen
near – Coordinate of the near clipping plane
far – Coordinate of the far clipping plane
-
classmethod
perspective_projection_fov
(fov: float, aspect: float, near: float, far: float) → Matrix44¶ Returns a matrix for a 2D projection.
- Parameters
fov – The field of view (in radians)
aspect – The aspect ratio of the screen (width / height)
near – Coordinate of the near clipping plane
far – Coordinate of the far clipping plane
-
static
chain
(*matrices: Iterable[Matrix44]) → Matrix44¶ Compose a transformation matrix from one or more matrices.
-
static
ucs
(ux: Vertex, uy: Vertex, uz: Vertex) → Matrix44¶ Returns a matrix for coordinate transformation from WCS to UCS. For transformation from UCS to WCS, transpose the returned matrix.
- Parameters
ux – x-axis for UCS as unit vector
uy – y-axis for UCS as unit vector
uz – z-axis for UCS as unit vector
origin – UCS origin as location vector
-
__hash__
() → int¶ Returns hash value of matrix.
-
__getitem__
(index: Tuple[int, int])¶ Get (row, column) element.
-
__setitem__
(index: Tuple[int, int], value: float)¶ Set (row, column) element.
-
__iter__
() → Iterable[float]¶ Iterates over all matrix values.
-
rows
() → Iterable[Tuple[float, …]]¶ Iterate over rows as 4-tuples.
-
columns
() → Iterable[Tuple[float, …]]¶ Iterate over columns as 4-tuples.
-
__mul__
(other: Matrix44) → Matrix44¶ Returns a new matrix as result of the matrix multiplication with another matrix.
-
fast_mul
(other: Matrix44) → Matrix44¶ Multiplies this matrix with other matrix.
Assumes that both matrices have a right column of (0, 0, 0, 1). This is True for matrices composed of rotations, translations and scales. fast_mul is approximately 25% quicker than the
*=
operator.
-
transform
(vector: Vertex) → ezdxf.math.vector.Vector¶ Returns a transformed vertex.
-
transform_direction
(vector: Vertex, normalize=False) → ezdxf.math.vector.Vector¶ Returns a transformed direction vector without translation.
-
transform_vertices
(vectors: Iterable[Vertex]) → Iterable[ezdxf.math.vector.Vector]¶ Returns an iterable of transformed vertices.
-
transform_directions
(vectors: Iterable[Vertex], normalize=False) → Iterable[ezdxf.math.vector.Vector]¶ Returns an iterable of transformed direction vectors without translation.
-
transpose
() → None¶ Swaps the rows for columns inplace.
-
determinant
() → float¶ Returns determinant.
-
inverse
() → None¶ Calculates the inverse of the matrix.
- Raises
ZeroDivisionError – if matrix has no inverse.
Construction Tools¶
Vector¶
-
class
ezdxf.math.
Vector
(*args)¶ This is an immutable universal 3D vector object. This class is optimized for universality not for speed. Immutable means you can’t change (x, y, z) components after initialization:
v1 = Vector(1, 2, 3) v2 = v1 v2.z = 7 # this is not possible, raises AttributeError v2 = Vector(v2.x, v2.y, 7) # this creates a new Vector() object assert v1.z == 3 # and v1 remains unchanged
Vector
initialization:Vector()
, returnsVector(0, 0, 0)
Vector((x, y))
, returnsVector(x, y, 0)
Vector((x, y, z))
, returnsVector(x, y, z)
Vector(x, y)
, returnsVector(x, y, 0)
Vector(x, y, z)
, returnsVector(x, y, z)
Addition, subtraction, scalar multiplication and scalar division left and right handed are supported:
v = Vector(1, 2, 3) v + (1, 2, 3) == Vector(2, 4, 6) (1, 2, 3) + v == Vector(2, 4, 6) v - (1, 2, 3) == Vector(0, 0, 0) (1, 2, 3) - v == Vector(0, 0, 0) v * 3 == Vector(3, 6, 9) 3 * v == Vector(3, 6, 9) Vector(3, 6, 9) / 3 == Vector(1, 2, 3) -Vector(1, 2, 3) == (-1, -2, -3)
Comparison between vectors and vectors or tuples is supported:
Vector(1, 2, 3) < Vector (2, 2, 2) (1, 2, 3) < tuple(Vector(2, 2, 2)) # conversion necessary Vector(1, 2, 3) == (1, 2, 3) bool(Vector(1, 2, 3)) is True bool(Vector(0, 0, 0)) is False
-
x
¶ x-axis value
-
y
¶ y-axis value
-
z
¶ z-axis value
-
xy
¶ Vector as
(x, y, 0)
, projected on the xy-plane.
-
xyz
¶ Vector as
(x, y, z)
tuple.
-
magnitude
¶ Length of vector.
-
magnitude_xy
¶ Length of vector in the xy-plane.
-
magnitude_square
¶ Square length of vector.
-
is_null
¶ True
forVector(0, 0, 0)
.
-
angle
¶ Angle between vector and x-axis in the xy-plane in radians.
-
angle_deg
¶ Returns angle of vector and x-axis in the xy-plane in degrees.
-
spatial_angle
¶ Spatial angle between vector and x-axis in radians.
-
spatial_angle_deg
¶ Spatial angle between vector and x-axis in degrees.
-
__str__
() → str¶ Return
'(x, y, z)'
as string.
-
__repr__
() → str¶ Return
'Vector(x, y, z)'
as string.
-
__len__
() → int¶ Returns always
3
.
-
__hash__
() → int¶ Returns hash value of vector, enables the usage of vector as key in
set
anddict
.
-
__getitem__
(index: int) → float¶ Support for indexing:
v[0] is v.x
v[1] is v.y
v[2] is v.z
-
__iter__
() → Iterable[float]¶ Returns iterable of x-, y- and z-axis.
-
__abs__
() → float¶ Returns length (magnitude) of vector.
-
replace
(x: float = None, y: float = None, z: float = None) → Vector¶ Returns a copy of vector with replaced x-, y- and/or z-axis.
-
classmethod
generate
(items: Iterable[Vertex]) → Iterable[Vector]¶ Returns an iterable of
Vector
objects.
-
classmethod
from_angle
(angle: float, length: float = 1.) → Vector¶ Returns a
Vector
object from angle in radians in the xy-plane, z-axis =0
.
-
classmethod
from_deg_angle
(angle: float, length: float = 1.) → Vector¶ Returns a
Vector
object from angle in degrees in the xy-plane, z-axis =0
.
-
orthogonal
(ccw: bool = True) → Vector¶ Returns orthogonal 2D vector, z-axis is unchanged.
- Parameters
ccw – counter clockwise if
True
else clockwise
-
lerp
(other: Any, factor=.5) → Vector¶ Returns linear interpolation between self and other.
- Parameters
other – end point as
Vector
compatible objectfactor – interpolation factor (
0
= self,1
= other,0.5
= mid point)
-
is_parallel
(other: Vector, abs_tolr=1e-12) → bool¶ Returns
True
if self and other are parallel to vectors.
-
isclose
(other: Any, abs_tol: float = 1e-12) → bool¶ Returns
True
if self is close to other. Usesmath.isclose()
to compare all axis.
-
__bool__
() → bool¶ Returns
True
if vector is not(0, 0, 0)
.
-
__add__
(other: Any) → Vector¶ Add operator: self + other
- Parameters
other –
Vector
compatible object
-
__radd__
(other: Any) → Vector¶ RAdd operator: other + self
- Parameters
other –
Vector
compatible object
-
__sub__
(other: Any) → Vector¶ Sub operator: self - other
- Parameters
other –
Vector
compatible object
-
__rsub__
(other: Any) → Vector¶ RSub operator: other - self
- Parameters
other –
Vector
compatible object
-
distance
(other: Any) → float¶ Returns distance between self and other vector.
-
angle_about
(base: Vector, target: Vector) → float¶ Returns counter clockwise angle in radians about self from base to target when projected onto the plane defined by self as the normal vector.
- Parameters
base – base vector, defines angle 0
target – target vector
-
angle_between
(other: Any) → float¶ Returns angle between self and other in radians. +angle is counter clockwise orientation.
- Parameters
other –
Vector
compatible object
-
ezdxf.math.
X_AXIS
¶ Vector(1, 0, 0)
-
ezdxf.math.
Y_AXIS
¶ Vector(0, 1, 0)
-
ezdxf.math.
Z_AXIS
¶ Vector(0, 0, 1)
-
ezdxf.math.
NULLVEC
¶ Vector(0, 0, 0)
Vec2¶
-
class
ezdxf.math.
Vec2
(v)¶ Vec2
represents a special 2D vector(x, y)
. TheVec2
class is optimized for speed and not immutable,iadd()
,isub()
,imul()
andidiv()
modifies the vector itself, theVector
class returns a new object.Vec2
initialization accepts float-tuples(x, y[, z])
, two floats or any object providingx
andy
attributes likeVec2
andVector
objects.- Parameters
v – vector object with
x
andy
attributes/properties or a sequence of float[x, y, ...]
or x-axis as float if argument y is notNone
y – second float for
Vec2(x, y)
Plane¶
-
class
ezdxf.math.
Plane
(normal: Vector, distance: float)¶ Represents a plane in 3D space as normal vector and the perpendicular distance from origin.
New in version 0.11.
-
normal
¶ Normal vector of the plane.
-
distance_from_origin
¶ The (perpendicular) distance of the plane from origin (0, 0, 0).
-
vector
¶ Returns the location vector.
-
classmethod
from_3p
(a: Vector, b: Vector, c: Vector) → Plane¶ Returns a new plane from 3 points in space.
-
signed_distance_to
(v: Vector) → float¶ Returns signed distance of vertex v to plane, if distance is > 0, v is in ‘front’ of plane, in direction of the normal vector, if distance is < 0, v is at the ‘back’ of the plane, in the opposite direction of the normal vector.
-
BoundingBox¶
-
class
ezdxf.math.
BoundingBox
(vertices: Iterable[Vertex] = None)¶ 3D bounding box.
- Parameters
vertices – iterable of
(x, y, z)
tuples orVector
objects
-
extmin
¶ “lower left” corner of bounding box
-
extmax
¶ “upper right” corner of bounding box
-
property
center
¶ Returns center of bounding box.
-
extend
(vertices: Iterable[Vertex]) → None¶ Extend bounds by vertices.
- Parameters
vertices – iterable of
(x, y, z)
tuples orVector
objects
-
property
has_data
¶ Returns
True
if data is available
-
inside
(vertex: Vertex) → bool¶ Returns
True
if vertex is inside bounding box.
-
property
size
¶ Returns size of bounding box.
BoundingBox2d¶
-
class
ezdxf.math.
BoundingBox2d
(vertices: Iterable[Vertex] = None)¶ Optimized 2D bounding box.
- Parameters
vertices – iterable of
(x, y[, z])
tuples orVector
objects
-
extmin
¶ “lower left” corner of bounding box
-
extmax
¶ “upper right” corner of bounding box
-
property
center
¶ Returns center of bounding box.
-
extend
(vertices: Iterable[Vertex]) → None¶ Extend bounds by vertices.
- Parameters
vertices – iterable of
(x, y[, z])
tuples orVector
objects
-
property
has_data
¶ Returns
True
if data is available
-
inside
(vertex: Vertex) → bool¶ Returns
True
if vertex is inside bounding box.
-
property
size
¶ Returns size of bounding box.
ConstructionRay¶
-
class
ezdxf.math.
ConstructionRay
(p1: Vertex, p2: Vertex = None, angle: float = None)¶ Infinite 2D construction ray as immutable object.
- Parameters
p1 – definition point 1
p2 – ray direction as 2nd point or
None
angle – ray direction as angle in radians or
None
-
slope
¶ Slope of ray or
None
if vertical.
-
angle
¶ Angle between x-axis and ray in radians.
-
angle_deg
¶ Angle between x-axis and ray in degrees.
-
is_vertical
¶ True
if ray is vertical (parallel to y-axis).
-
is_horizontal
¶ True
if ray is horizontal (parallel to x-axis).
-
__str__
()¶ Return str(self).
-
is_parallel
(self, other: ConstructionRay) → bool¶ Returns
True
if rays are parallel.
-
intersect
(other: ConstructionRay) → Vec2¶ Returns the intersection point as
(x, y)
tuple of self and other.- Raises
ParallelRaysError – if rays are parallel
-
orthogonal
(location: Vertex) → ConstructionRay¶ Returns orthogonal ray at location.
-
bisectrix
(other: ConstructionRay) → ConstructionRay:¶ Bisectrix between self and other.
-
yof
(x: float) → float¶ Returns y-value of ray for x location.
- Raises
ArithmeticError – for vertical rays
-
xof
(y: float) → float¶ Returns x-value of ray for y location.
- Raises
ArithmeticError – for horizontal rays
ConstructionLine¶
-
class
ezdxf.math.
ConstructionLine
(start: Vertex, end: Vertex)¶ 2D ConstructionLine is similar to
ConstructionRay
, but has a start- and endpoint. The direction of line goes from start- to endpoint, “left of line” is always in relation to this line direction.- Parameters
-
bounding_box
¶ bounding box of line as
BoundingBox2d
object.
-
ray
¶ collinear
ConstructionRay
.
-
is_vertical
¶ True
if line is vertical.
-
__str__
()¶ Return str(self).
-
translate
(dx: float, dy: float) → None¶ Move line about dx in x-axis and about dy in y-axis.
- Parameters
dx – translation in x-axis
dy – translation in y-axis
-
length
() → float¶ Returns length of line.
-
inside_bounding_box
(point: Vertex) → bool¶ Returns
True
if point is inside of line bounding box.
-
intersect
(other: ConstructionLine, abs_tol: float = 1e-10) → Optional[Vec2]¶ Returns the intersection point of to lines or
None
if they have no intersection point.- Parameters
other – other
ConstructionLine
abs_tol – tolerance for distance check
-
has_intersection
(other: ConstructionLine, abs_tol: float = 1e-10) → bool¶ Returns
True
if has intersection with other line.
-
is_point_left_of_line
(point: Vertex, colinear=False) → bool¶ Returns
True
if point is left of construction line in relation to the line direction from start to end.If colinear is
True
, a colinear point is also left of the line.
ConstructionCircle¶
-
class
ezdxf.math.
ConstructionCircle
(center: Vertex, radius: float = 1.0)¶ Circle construction tool.
- Parameters
center – center point as
Vec2
compatible objectradius – circle radius > 0
-
radius
¶ radius as float
-
bounding_box
¶ 2D bounding box of circle as
BoundingBox2d
object.
-
static
from_3p
(p1: Vertex, p2: Vertex, p3: Vertex) → ConstructionCircle¶ Creates a circle from three points, all points have to be compatible to
Vec2
class.
-
__str__
() → str¶ Returns string representation of circle “ConstructionCircle(center, radius)”.
-
translate
(dx: float, dy: float) → None¶ Move circle about dx in x-axis and about dy in y-axis.
- Parameters
dx – translation in x-axis
dy – translation in y-axis
-
point_at
(angle: float) → Vec2¶ Returns point on circle at angle as
Vec2
object.- Parameters
angle – angle in radians
-
inside
(point: Vertex) → bool¶ Returns
True
if point is inside circle.
-
tangent
(angle: float) → ConstructionRay¶ Returns tangent to circle at angle as
ConstructionRay
object.- Parameters
angle – angle in radians
-
intersect_ray
(ray: ConstructionRay, abs_tol: float = 1e-10) → Sequence[Vec2]¶ Returns intersection points of circle and ray as sequence of
Vec2
objects.- Parameters
ray – intersection ray
abs_tol – absolute tolerance for tests (e.g. test for tangents)
- Returns
tuple of
Vec2
objectstuple size
Description
0
no intersection
1
ray is a tangent to circle
2
ray intersects with the circle
-
intersect_circle
(other: ConstructionCircle, abs_tol: float = 1e-10) → Sequence[Vec2]¶ Returns intersection points of two circles as sequence of
Vec2
objects.- Parameters
other – intersection circle
abs_tol – absolute tolerance for tests
- Returns
tuple of
Vec2
objectstuple size
Description
0
no intersection
1
circle touches the other circle at one point
2
circle intersects with the other circle
ConstructionArc¶
-
class
ezdxf.math.
ConstructionArc
(center: Vertex = (0, 0), radius: float = 1, start_angle: float = 0, end_angle: float = 360, is_counter_clockwise: bool = True)¶ This is a helper class to create parameters for the DXF
Arc
class.ConstructionArc
represents a 2D arc in the xy-plane, use anUCS
to place arc in 3D space, see methodadd_to_layout()
.Implements the 2D transformation tools:
translate()
,scale_uniform()
androtate_z()
- Parameters
center – center point as
Vec2
compatible objectradius – radius
start_angle – start angle in degrees
end_angle – end angle in degrees
is_counter_clockwise – swaps start- and end angle if
False
-
radius
¶ radius as float
-
start_angle
¶ start angle in degrees
-
end_angle
¶ end angle in degrees
-
angle_span
¶ Returns angle span of arc from start- to end param.
-
start_angle_rad
¶ Returns the start angle in radians.
-
end_angle_rad
¶ Returns the end angle in radians.
-
bounding_box
¶ bounding box of arc as
BoundingBox2d
.
-
angles
(num: int) → Iterable[float]¶ Returns num angles from start- to end angle in degrees in counter clockwise order.
All angles are normalized in the range from [0, 360).
-
vertices
(a: Iterable[float]) → Iterable[ezdxf.math.vector.Vec2]¶ Yields vertices on arc for angles in iterable a in WCS as location vectors.
- Parameters
a – angles in the range from 0 to 360 in degrees, arc goes counter clockwise around the z-axis, WCS x-axis = 0 deg.
-
tangents
(a: Iterable[float]) → Iterable[ezdxf.math.vector.Vec2]¶ Yields tangents on arc for angles in iterable a in WCS as direction vectors.
- Parameters
a – angles in the range from 0 to 360 in degrees, arc goes counter clockwise around the z-axis, WCS x-axis = 0 deg.
-
translate
(dx: float, dy: float) → ConstructionArc¶ Move arc about dx in x-axis and about dy in y-axis, returns self (floating interface).
- Parameters
dx – translation in x-axis
dy – translation in y-axis
-
scale_uniform
(s: float) → ConstructionArc¶ Scale arc inplace uniform about s in x- and y-axis, returns self (floating interface).
-
rotate_z
(angle: float) → ConstructionArc¶ Rotate arc inplace about z-axis, returns self (floating interface).
- Parameters
angle – rotation angle in degrees
-
classmethod
from_2p_angle
(start_point: Vertex, end_point: Vertex, angle: float, ccw: bool = True) → ConstructionArc¶ Create arc from two points and enclosing angle. Additional precondition: arc goes by default in counter clockwise orientation from start_point to end_point, can be changed by ccw =
False
.
-
classmethod
from_2p_radius
(start_point: Vertex, end_point: Vertex, radius: float, ccw: bool = True, center_is_left: bool = True) → ConstructionArc¶ Create arc from two points and arc radius. Additional precondition: arc goes by default in counter clockwise orientation from start_point to end_point can be changed by ccw =
False
.The parameter center_is_left defines if the center of the arc is left or right of the line from start_point to end_point. Parameter ccw =
False
swaps start- and end point, which also inverts the meaning ofcenter_is_left
.
-
classmethod
from_3p
(start_point: Vertex, end_point: Vertex, def_point: Vertex, ccw: bool = True) → ConstructionArc¶ Create arc from three points. Additional precondition: arc goes in counter clockwise orientation from start_point to end_point.
-
add_to_layout
(layout: BaseLayout, ucs: UCS = None, dxfattribs: dict = None) → Arc¶ Add arc as DXF
Arc
entity to a layout.Supports 3D arcs by using an UCS. An
ConstructionArc
is always defined in the xy-plane, but by using an arbitrary UCS, the arc can be placed in 3D space, automatically OCS transformation included.- Parameters
layout – destination layout as
BaseLayout
objectucs – place arc in 3D space by
UCS
objectdxfattribs – additional DXF attributes for the DXF
Arc
entity
ConstructionEllipse¶
-
class
ezdxf.math.
ConstructionEllipse
(center: Vertex = Vector(0.0, 0.0, 0.0), major_axis: Vertex = Vector(1.0, 0.0, 0.0), extrusion: Vertex = Vector(0.0, 0.0, 1.0), ratio: float = 1, start_param: float = 0, end_param: float = 6.283185307179586, ccw: bool = True)¶ This is a helper class to create parameters for 3D ellipses.
- Parameters
center – 3D center point
major_axis – major axis as 3D vector
extrusion – normal vector of ellipse plane
ratio – ratio of minor axis to major axis
start_param – start param in radians
end_param – end param in radians
ccw – is counter clockwise flag - swaps start- and end param if
False
-
minor_axis
¶ minor axis as
Vector
, automatically calculated frommajor_axis
andextrusion
.
-
ratio
¶ ratio of minor axis to major axis (float)
-
start
¶ start param in radians (float)
-
end
¶ end param in radians (float)
-
start_point
¶ Returns start point of ellipse as Vector.
-
end_point
¶ Returns end point of ellipse as Vector.
-
to_ocs
() → ConstructionEllipse¶ Returns ellipse parameters as OCS representation.
OCS elevation is stored in
center.z
.
-
params
(num: int) → Iterable[float]¶ Returns num params from start- to end param in counter clockwise order.
All params are normalized in the range from [0, 2pi).
-
vertices
(params: Iterable[float]) → Iterable[ezdxf.math.vector.Vector]¶ Yields vertices on ellipse for iterable params in WCS.
- Parameters
params – param values in the range from
0
to2*pi
in radians, param goes counter clockwise around the extrusion vector, major_axis = local x-axis = 0 rad.
-
params_from_vertices
(vertices: Iterable[Vertex]) → Iterable[float]¶ Yields ellipse params for all given vertices.
The vertex don’t has to be exact on the ellipse curve or in the range from start- to end param or even in the ellipse plane. Param is calculated from the intersection point of the ray projected on the ellipse plane from the center of the ellipse through the vertex.
Warning
An input for start- and end vertex at param 0 and 2*pi return unpredictable results because of floating point inaccuracy, sometimes 0 and sometimes 2*pi.
-
dxfattribs
() → Dict¶ Returns required DXF attributes to build an ELLIPSE entity.
Entity ELLIPSE has always a ratio in range from 1e-6 to 1.
-
main_axis_points
() → Iterable[ezdxf.math.vector.Vector]¶ Yields main axis points of ellipse in the range from start- to end param.
-
classmethod
from_arc
(center: Vertex = (0, 0, 0), radius: float = 1, extrusion: Vertex = (0, 0, 1), start_angle: float = 0, end_angle: float = 360, ccw: bool = True) → ConstructionEllipse¶ Returns
ConstructionEllipse
from arc or circle.Arc and Circle parameters defined in OCS.
- Parameters
center – center in OCS
radius – arc or circle radius
extrusion – OCS extrusion vector
start_angle – start angle in degrees
end_angle – end angle in degrees
ccw – arc curve goes counter clockwise from start to end if
True
-
swap_axis
() → None¶ Swap axis and adjust start- and end parameter.
-
add_to_layout
(layout: BaseLayout, dxfattribs: dict = None) → Ellipse¶ Add ellipse as DXF
Ellipse
entity to a layout.- Parameters
layout – destination layout as
BaseLayout
objectdxfattribs – additional DXF attributes for DXF
Ellipse
entity
ConstructionBox¶
-
class
ezdxf.math.
ConstructionBox
(center: Vertex = (0, 0), width: float = 1, height: float = 1, angle: float = 0)¶ Helper class to create rectangles.
- Parameters
center – center of rectangle
width – width of rectangle
height – height of rectangle
angle – angle of rectangle in degrees
-
center
¶ box center
-
width
¶ box width
-
height
¶ box height
-
angle
¶ rotation angle in degrees
-
bounding_box
¶
-
incircle_radius
¶ incircle radius
-
circumcircle_radius
¶ circum circle radius
-
__repr__
() → str¶ Returns string representation of box as
ConstructionBox(center, width, height, angle)
-
classmethod
from_points
(p1: Vertex, p2: Vertex) → ConstructionBox¶ Creates a box from two opposite corners, box sides are parallel to x- and y-axis.
-
translate
(dx: float, dy: float) → None¶ Move box about dx in x-axis and about dy in y-axis.
- Parameters
dx – translation in x-axis
dy – translation in y-axis
-
expand
(dw: float, dh: float) → None¶ Expand box: dw expand width, dh expand height.
-
scale
(sw: float, sh: float) → None¶ Scale box: sw scales width, sh scales height.
-
rotate
(angle: float) → None¶ Rotate box by angle in degrees.
-
is_inside
(point: Vertex) → bool¶ Returns
True
if point is inside of box.
-
is_any_corner_inside
(other: ConstructionBox) → bool¶ Returns
True
if any corner of other box is inside this box.
-
is_overlapping
(other: ConstructionBox) → bool¶ Returns
True
if this box and other box do overlap.
-
border_lines
() → Sequence[ConstructionLine]¶ Returns border lines of box as sequence of
ConstructionLine
.
-
intersect
(line: ConstructionLine) → List[Vec2]¶ Returns 0, 1 or 2 intersection points between line and box border lines.
- Parameters
line – line to intersect with border lines
- Returns
list of intersection points
list size
Description
0
no intersection
1
line touches box at one corner
2
line intersects with box
Shape2d¶
-
class
ezdxf.math.
Shape2d
(vertices: Iterable[Vertex] = None)¶ 2D geometry object as list of
Vec2
objects, vertices can be moved, rotated and scaled.- Parameters
vertices – iterable of
Vec2
compatible objects.
-
bounding_box
¶
-
__len__
() → int¶ Returns count of vertices.
-
append
(vertex: Vertex) → None¶ Append single vertex.
- Parameters
vertex – vertex as
Vec2
compatible object
-
extend
(vertices: Iterable) → None¶ Append multiple vertices.
- Parameters
vertices – iterable of vertices as
Vec2
compatible objects
-
translate
(vector: Vertex) → None¶ Translate shape about vector.
-
scale
(sx: float = 1.0, sy: float = 1.0) → None¶ Scale shape about sx in x-axis and sy in y-axis.
-
scale_uniform
(scale: float) → None¶ Scale shape uniform about scale in x- and y-axis.
-
rotate
(angle: float, center: Vertex = None) → None¶ Rotate shape around rotation center about angle in degrees.
-
rotate_rad
(angle: float, center: Vertex = None) → None¶ Rotate shape around rotation center about angle in radians.
-
offset
(offset: float, closed: bool = False) → ezdxf.math.shape.Shape2d¶ Returns a new offset shape, for more information see also
ezdxf.math.offset_vertices_2d()
function.New in version 0.11.
- Parameters
offset – line offset perpendicular to direction of shape segments defined by vertices order, offset >
0
is ‘left’ of line segment, offset <0
is ‘right’ of line segmentclosed –
True
to handle as closed shape
-
convex_hull
() → ezdxf.math.shape.Shape2d¶ Returns convex hull as new shape.
Curves¶
BSpline¶
-
class
ezdxf.math.
BSpline
(control_points: Iterable[Vertex], order: int = 4, knots: Iterable[float] = None, weights: Iterable[float] = None)¶ Representation of a B-spline curve, using an uniform open knot vector (“clamped”).
- Parameters
control_points – iterable of control points as
Vector
compatible objectsorder – spline order (degree + 1)
knots – iterable of knot values
weights – iterable of weight values
-
count
¶ Count of control points, (n + 1 in text book notation).
-
degree
¶ Degree (p) of B-spline = order - 1
-
order
¶ Order of B-spline = degree + 1
-
is_rational
¶ Returns
True
if curve is a rational B-spline. (has weights)
-
knots
() → List[float]¶ Returns a list of knot values as floats, the knot vector always has order + count values (n + p + 2 in text book notation).
-
normalize_knots
()¶ Normalize knot vector into range [0, 1].
-
weights
() → List[float]¶ Returns a list of weights values as floats, one for each control point or an empty list.
-
params
(segments: int) → Iterable[float]¶ Yield evenly spaced parameters from 0 to max_t for given segment count.
-
transform
(m: Matrix44) → BSpline¶ Transform B-spline by transformation matrix m inplace.
New in version 0.13.
-
approximate
(segments: int = 20) → Iterable[Vector]¶ Approximates curve by vertices as
Vector
objects, vertices count = segments + 1.
-
point
(t: float) → Vector¶ Returns point for parameter t.
- Parameters
t – parameter in range [0, max_t]
-
points
(t: float) → List[Vector]¶ Yields points for parameter vector t.
- Parameters
t – parameters in range [0, max_t]
-
derivative
(t: float, n: int = 2) → List[Vector]¶ Return point and derivatives up to n <= degree for parameter t.
e.g. n=1 returns point and 1st derivative.
- Parameters
t – parameter in range [0, max_t]
n – compute all derivatives up to n <= degree
- Returns
n+1 values as
Vector
objects
-
derivatives
(t: Iterable[float], n: int = 2) → Iterable[List[Vector]]¶ Yields points and derivatives up to n <= degree for parameter vector t.
e.g. n=1 returns point and 1st derivative.
- Parameters
t – parameters in range [0, max_t]
n – compute all derivatives up to n <= degree
- Returns
List of n+1 values as
Vector
objects
-
insert_knot
(t: float) → None¶ Insert additional knot, without altering the curve shape.
- Parameters
t – position of new knot 0 < t < max_t
-
static
from_ellipse
(ellipse: ConstructionEllipse) → BSpline¶ Returns the ellipse as
BSpline
of 2nd degree with as few control points as possible.
-
static
from_arc
(arc: ConstructionArc) → BSpline¶ Returns the arc as
BSpline
of 2nd degree with as few control points as possible.
-
static
from_fit_points
(points: Iterable[Vertex], degree: int = 3, method='chord') → BSpline¶ Returns
BSpline
defined by fit points.
-
static
arc_approximation
(arc: ConstructionArc, num: int = 16) → BSpline¶ Returns an arc approximation as
BSpline
with num control points.
-
static
ellipse_approximation
(ellipse: ConstructionEllipse, num: int = 16) → BSpline¶ Returns an ellipse approximation as
BSpline
with num control points.
-
bezier_decomposition
() → Iterable[List[Vector]]¶ Decompose a non-rational B-spline into multiple Bézier curves.
This is the preferred method to represent the most common non-rational B-splines of 3rd degree by cubic Bézier curves, which are often supported by render backends.
- Returns
Yields control points of Bézier curves, each Bézier segment has degree+1 control points e.g. B-spline of 3rd degree yields cubic Bézier curves of 4 control points.
-
cubic_bezier_approximation
(level: int = 3, segments: int = None) → Iterable[Bezier4P]¶ Approximate arbitrary B-splines (degree != 3 and/or rational) by multiple segments of cubic Bézier curves. The choice of cubic Bézier curves is based on the widely support of this curves by many render backends. For cubic non-rational B-splines, which is maybe the most common used B-spline, is
bezier_decomposition()
the better choice.1. approximation by level: an educated guess, the first level of approximation segments is based on the count of control points and their distribution along the B-spline, every additional level is a subdivision of the previous level. E.g. a B-Spline of 8 control points has 7 segments at the first level, 14 at the 2nd level and 28 at the 3rd level, a level >= 3 is recommended.
approximation by a given count of evenly distributed approximation segments.
- Parameters
level – subdivision level of approximation segments (ignored if argument
segments
!=None
)segments – absolute count of approximation segments
- Returns
Yields control points of cubic Bézier curves as
Bezier4P
objects
BSplineU¶
-
class
ezdxf.math.
BSplineU
(control_points: Iterable[Vertex], order: int = 4, knots: Iterable[float] = None, weights: Iterable[float] = None)¶ Representation of an uniform (periodic) B-spline curve (open curve).
BSplineClosed¶
-
class
ezdxf.math.
BSplineClosed
(control_points: Iterable[Vertex], order: int = 4, knots: Iterable[float] = None, weights: Iterable[float] = None)¶ Representation of a closed uniform B-spline curve (closed curve).
Bezier¶
-
class
ezdxf.math.
Bezier
(defpoints: Iterable[Vertex])¶ A Bézier curve is a parametric curve used in computer graphics and related fields. Bézier curves are used to model smooth curves that can be scaled indefinitely. “Paths”, as they are commonly referred to in image manipulation programs, are combinations of linked Bézier curves. Paths are not bound by the limits of rasterized images and are intuitive to modify. (Source: Wikipedia)
This is a general implementation which works with any count of definition points greater than
2
, but it is a simple and slow implementation. For more performance look at the specializedBezier4P
class.Objects are immutable.
- Parameters
defpoints – iterable of definition points as
Vector
compatible objects.
-
params
(segments: int) → Iterable[float]¶ Yield evenly spaced parameters from 0 to 1 for given segment count.
-
transform
(m: Matrix44) → Bezier¶ General transformation interface, returns a new
Bezier
curve.- Parameters
m – 4x4 transformation matrix (
ezdxf.math.Matrix44
)
New in version 0.14.
-
approximate
(segments: int = 20) → Iterable[Vector]¶ Approximates curve by vertices as
Vector
objects, vertices count = segments + 1.
-
points
(t: Iterable[float]) → Iterable[Vector]¶ Yields multiple points for parameters in vector t as
Vector
objects. Parameters have to be in range [0, 1].
Bezier4P¶
-
class
ezdxf.math.
Bezier4P
(defpoints: Sequence[Vertex])¶ Implements an optimized cubic Bézier curve for exact 4 control points. A Bézier curve is a parametric curve, parameter t goes from
0
to1
, where0
is the first control point and1
is the fourth control point.Special behavior:
-
transform
(m: Matrix44) → Bezier4P¶ General transformation interface, returns a new
Bezier4p
curve and it is always a 3D curve.- Parameters
m – 4x4 transformation matrix (
ezdxf.math.Matrix44
)
New in version 0.14.
-
approximate
(segments: int) → Iterable[Union[Vector, Vec2]]¶ Approximate Bézier curve by vertices, yields segments + 1 vertices as
(x, y[, z])
tuples.- Parameters
segments – count of segments for approximation
-
approximated_length
(segments: int = 128) → float¶ Returns estimated length of Bèzier-curve as approximation by line segments.
-
BezierSurface¶
-
class
ezdxf.math.
BezierSurface
(defpoints: List[List[Sequence[float]]])¶ BezierSurface
defines a mesh of m x n control points. This is a parametric surface, which means the m-dimension goes from0
to1
as parameter u and the n-dimension goes from0
to1
as parameter v.- Parameters
defpoints – matrix (list of lists) of m rows and n columns: [ [m1n1, m1n2, … ], [m2n1, m2n2, …] … ] each element is a 3D location as
(x, y, z)
tuple.
-
nrows
¶ count of rows (m-dimension)
-
ncols
¶ count of columns (n-dimension)
-
point
(u: float, v: float) → Sequence[float]¶ Returns a point for location (u, v) at the Bézier surface as
(x, y, z)
tuple, parameters u and v in the range of[0, 1]
.
-
approximate
(usegs: int, vsegs: int) → List[List[Sequence[float]]]¶ Approximate surface as grid of
(x, y, z)
tuples.- Parameters
usegs – count of segments in u-direction (m-dimension)
vsegs – count of segments in v-direction (n-dimension)
- Returns
list of usegs + 1 rows, each row is a list of vsegs + 1 vertices as
(x, y, z)
tuples.
EulerSpiral¶
-
class
ezdxf.math.
EulerSpiral
(curvature: float = 1.0)¶ This class represents an euler spiral (clothoid) for curvature (Radius of curvature).
This is a parametric curve, which always starts at the origin =
(0, 0)
.- Parameters
curvature – radius of curvature
-
radius
(t: float) → float¶ Get radius of circle at distance t.
-
distance
(radius: float) → float¶ Get distance L from origin for radius.
-
circle_center
(t: float) → Vector¶ Get circle center at distance t.
Changed in version 0.10: renamed from circle_midpoint
-
approximate
(length: float, segments: int) → Iterable[Vector]¶ Approximate curve of length with line segments.
Generates segments+1 vertices as
Vector
objects.
-
bspline
(length: float, segments: int = 10, degree: int = 3, method: str = 'uniform') → BSpline¶ Approximate euler spiral as B-spline.
- Parameters
length – length of euler spiral
segments – count of fit points for B-spline calculation
degree – degree of BSpline
method – calculation method for parameter vector t
- Returns
Linear Algebra¶
Functions¶
-
ezdxf.math.
gauss_jordan_solver
(A: Iterable[Iterable[float]], B: Iterable[Iterable[float]]) → Tuple[Matrix, Matrix]¶ Solves the linear equation system given by a nxn Matrix A . x = B, right-hand side quantities as nxm Matrix B by the Gauss-Jordan algorithm, which is the slowest of all, but it is very reliable. Returns a copy of the modified input matrix A and the result matrix x.
Internally used for matrix inverse calculation.
- Parameters
A – matrix [[a11, a12, …, a1n], [a21, a22, …, a2n], [a21, a22, …, a2n], … [an1, an2, …, ann]]
B – matrix [[b11, b12, …, b1m], [b21, b22, …, b2m], … [bn1, bn2, …, bnm]]
- Returns
2-tuple of
Matrix
objects- Raises
ZeroDivisionError – singular matrix
New in version 0.13.
-
ezdxf.math.
gauss_jordan_inverse
(A: Iterable[Iterable[float]]) → Matrix¶ Returns the inverse of matrix A as
Matrix
object.Hint
For small matrices (n<10) is this function faster than LUDecomposition(m).inverse() and as fast even if the decomposition is already done.
- Raises
ZeroDivisionError – singular matrix
New in version 0.13.
-
ezdxf.math.
gauss_vector_solver
(A: Iterable[Iterable[float]], B: Iterable[float]) → List[float]¶ Solves the linear equation system given by a nxn Matrix A . x = B, right-hand side quantities as vector B with n elements by the Gauss-Elimination algorithm, which is faster than the Gauss-Jordan algorithm. The speed improvement is more significant for solving multiple right-hand side quantities as matrix at once.
Reference implementation for error checking.
- Parameters
A – matrix [[a11, a12, …, a1n], [a21, a22, …, a2n], [a21, a22, …, a2n], … [an1, an2, …, ann]]
B – vector [b1, b2, …, bn]
- Returns
vector as list of floats
- Raises
ZeroDivisionError – singular matrix
New in version 0.13.
-
ezdxf.math.
gauss_matrix_solver
(A: Iterable[Iterable[float]], B: Iterable[Iterable[float]]) → Matrix¶ Solves the linear equation system given by a nxn Matrix A . x = B, right-hand side quantities as nxm Matrix B by the Gauss-Elimination algorithm, which is faster than the Gauss-Jordan algorithm.
Reference implementation for error checking.
- Parameters
A – matrix [[a11, a12, …, a1n], [a21, a22, …, a2n], [a21, a22, …, a2n], … [an1, an2, …, ann]]
B – matrix [[b11, b12, …, b1m], [b21, b22, …, b2m], … [bn1, bn2, …, bnm]]
- Returns
matrix as
Matrix
object- Raises
ZeroDivisionError – singular matrix
New in version 0.13.
-
ezdxf.math.
tridiagonal_vector_solver
(A: Iterable[Iterable[float]], B: Iterable[float]) → List[float]¶ Solves the linear equation system given by a tri-diagonal nxn Matrix A . x = B, right-hand side quantities as vector B. Matrix A is diagonal matrix defined by 3 diagonals [-1 (a), 0 (b), +1 (c)].
Note: a0 is not used but has to be present, cn-1 is also not used and must not be present.
If an
ZeroDivisionError
exception occurs, the equation system can possibly be solved byBandedMatrixLU(A, 1, 1).solve_vector(B)
- Parameters
A –
diagonal matrix [[a0..an-1], [b0..bn-1], [c0..cn-1]]
[[b0, c0, 0, 0, ...], [a1, b1, c1, 0, ...], [0, a2, b2, c2, ...], ... ]
B – iterable of floats [[b1, b1, …, bn]
- Returns
list of floats
- Raises
ZeroDivisionError – singular matrix
New in version 0.13.
-
ezdxf.math.
tridiagonal_matrix_solver
(A: Iterable[Iterable[float]], B: Iterable[Iterable[float]]) → Matrix¶ Solves the linear equation system given by a tri-diagonal nxn Matrix A . x = B, right-hand side quantities as nxm Matrix B. Matrix A is diagonal matrix defined by 3 diagonals [-1 (a), 0 (b), +1 (c)].
Note: a0 is not used but has to be present, cn-1 is also not used and must not be present.
If an
ZeroDivisionError
exception occurs, the equation system can possibly be solved byBandedMatrixLU(A, 1, 1).solve_vector(B)
- Parameters
A –
diagonal matrix [[a0..an-1], [b0..bn-1], [c0..cn-1]]
[[b0, c0, 0, 0, ...], [a1, b1, c1, 0, ...], [0, a2, b2, c2, ...], ... ]
B – matrix [[b11, b12, …, b1m], [b21, b22, …, b2m], … [bn1, bn2, …, bnm]]
- Returns
matrix as
Matrix
object- Raises
ZeroDivisionError – singular matrix
New in version 0.13.
-
ezdxf.math.
banded_matrix
(A: Matrix, check_all=True) → Tuple[int, int]¶ Transform matrix A into a compact banded matrix representation. Returns compact representation as
Matrix
object and lower- and upper band count m1 and m2.- Parameters
A – input
Matrix
check_all – check all diagonals if
True
or abort testing after first all zero diagonal ifFalse
.
-
ezdxf.math.
detect_banded_matrix
(A: Matrix, check_all=True) → Tuple[int, int]¶ Returns lower- and upper band count m1 and m2.
- Parameters
A – input
Matrix
check_all – check all diagonals if
True
or abort testing after first all zero diagonal ifFalse
.
Matrix Class¶
-
class
ezdxf.math.
Matrix
(items: Any = None, shape: Tuple[int, int] = None, matrix: List[List[float]] = None)¶ Basic matrix implementation without any optimization for speed of memory usage. Matrix data is stored in row major order, this means in a list of rows, where each row is a list of floats. Direct access to the data is accessible by the attribute
Matrix.matrix
.The matrix can be frozen by function
freeze_matrix()
or methodMatrix.freeze()
, than the data is stored in immutable tuples.Initialization:
Matrix(shape=(rows, cols)) … new matrix filled with zeros
Matrix(matrix[, shape=(rows, cols)]) … from copy of matrix and optional reshape
Matrix([[row_0], [row_1], …, [row_n]]) … from Iterable[Iterable[float]]
Matrix([a1, a2, …, an], shape=(rows, cols)) … from Iterable[float] and shape
New in version 0.13.
-
nrows
¶ Count of matrix rows.
-
ncols
¶ Count of matrix columns.
-
shape
¶ Shape of matrix as (n, m) tuple for n rows and m columns.
-
static
reshape
(items: Iterable[float], shape: Tuple[int, int]) → ezdxf.math.linalg.Matrix¶ Returns a new matrix for iterable items in the configuration of shape.
-
classmethod
identity
(shape: Tuple[int, int]) → ezdxf.math.linalg.Matrix¶ Returns the identity matrix for configuration shape.
-
row
(index) → List[float]¶ Returns row index as list of floats.
-
iter_row
(index) → Iterable[float]¶ Yield values of row index.
-
col
(index) → List[float]¶ Return column index as list of floats.
-
iter_col
(index) → Iterable[float]¶ Yield values of column index.
-
diag
(index) → List[float]¶ Returns diagonal index as list of floats.
An index of
0
specifies the main diagonal, negative values specifies diagonals below the main diagonal and positive values specifies diagonals above the main diagonal.e.g. given a 4x4 matrix: index
0
is [00, 11, 22, 33], index-1
is [10, 21, 32] and index+1
is [01, 12, 23]
-
rows
() → List[List[float]]¶ Return a list of all rows.
-
cols
() → List[List[float]]¶ Return a list of all columns.
-
set_row
(index: int, items: Union[float, Iterable[float]] = 1.0) → None¶ Set row values to a fixed value or from an iterable of floats.
-
set_col
(index: int, items: Union[float, Iterable[float]] = 1.0) → None¶ Set column values to a fixed value or from an iterable of floats.
-
set_diag
(index: int = 0, items: Union[float, Iterable[float]] = 1.0) → None¶ Set diagonal values to a fixed value or from an iterable of floats.
An index of
0
specifies the main diagonal, negative values specifies diagonals below the main diagonal and positive values specifies diagonals above the main diagonal.e.g. given a 4x4 matrix: index
0
is [00, 11, 22, 33], index-1
is [10, 21, 32] and index+1
is [01, 12, 23]
-
append_row
(items: Sequence[float]) → None¶ Append a row to the matrix.
-
append_col
(items: Sequence[float]) → None¶ Append a column to the matrix.
-
swap_rows
(a: int, b: int) → None¶ Swap rows a and b inplace.
-
swap_cols
(a: int, b: int) → None¶ Swap columns a and b inplace.
-
determinant
() → float¶ Returns determinant of matrix, raises
ZeroDivisionError
if matrix is singular.
-
lu_decomp
() → LUDecomposition¶ Returns the LU decomposition as
LUDecomposition
object, a faster linear equation solver.
-
__getitem__
(item: Tuple[int, int]) → float¶ Get value by (row, col) index tuple, fancy slicing as known from numpy is not supported.
-
__setitem__
(item: Tuple[int, int], value: float)¶ Set value by (row, col) index tuple, fancy slicing as known from numpy is not supported.
-
__eq__
(other: Matrix) → bool¶ Returns
True
if matrices are equal, tolerance value for comparision is adjustable by the attributeMatrix.abs_tol
.
-
__add__
(other: Union[Matrix, float]) → Matrix¶ Matrix addition by another matrix or a float, returns a new matrix.
LUDecomposition Class¶
-
class
ezdxf.math.
LUDecomposition
(A: Iterable[Iterable[float]])¶ Represents a LU decomposition matrix of A, raise
ZeroDivisionError
for a singular matrix.This algorithm is a little bit faster than the Gauss-Elimination algorithm using CPython and much faster when using pypy.
The
LUDecomposition.matrix
attribute gives access to the matrix data as list of rows like in theMatrix
class, and theLUDecomposition.index
attribute gives access to the swapped row indices.- Parameters
A – matrix [[a11, a12, …, a1n], [a21, a22, …, a2n], [a21, a22, …, a2n], … [an1, an2, …, ann]]
- Raises
ZeroDivisionError – singular matrix
New in version 0.13.
-
nrows
¶ Count of matrix rows (and cols).
-
solve_vector
(B: Iterable[float]) → List[float]¶ Solves the linear equation system given by the nxn Matrix A . x = B, right-hand side quantities as vector B with n elements.
- Parameters
B – vector [b1, b2, …, bn]
- Returns
vector as list of floats
-
solve_matrix
(B: Iterable[Iterable[float]]) → Matrix¶ Solves the linear equation system given by the nxn Matrix A . x = B, right-hand side quantities as nxm Matrix B.
- Parameters
B – matrix [[b11, b12, …, b1m], [b21, b22, …, b2m], … [bn1, bn2, …, bnm]]
- Returns
matrix as
Matrix
object
-
inverse
() → Matrix¶ Returns the inverse of matrix as
Matrix
object, raiseZeroDivisionError
for a singular matrix.
-
determinant
() → float¶ Returns the determinant of matrix, raises
ZeroDivisionError
if matrix is singular.
BandedMatrixLU Class¶
-
class
ezdxf.math.
BandedMatrixLU
(A: ezdxf.math.linalg.Matrix, m1: int, m2: int)¶ Represents a LU decomposition of a compact banded matrix.
-
upper
¶ Upper triangle
-
lower
¶ Lower triangle
-
m1
¶ Lower band count, excluding main matrix diagonal
-
m2
¶ Upper band count, excluding main matrix diagonal
-
index
¶ Swapped indices
-
nrows
¶ Count of matrix rows.
-
solve_vector
(B: Iterable[float]) → List[float]¶ Solves the linear equation system given by the banded nxn Matrix A . x = B, right-hand side quantities as vector B with n elements.
- Parameters
B – vector [b1, b2, …, bn]
- Returns
vector as list of floats
-
solve_matrix
(B: Iterable[Iterable[float]]) → Matrix¶ Solves the linear equation system given by the banded nxn Matrix A . x = B, right-hand side quantities as nxm Matrix B.
- Parameters
B – matrix [[b11, b12, …, b1m], [b21, b22, …, b2m], … [bn1, bn2, …, bnm]]
- Returns
matrix as
Matrix
object
-
determinant
() → float¶ Returns the determinant of matrix.
-