This utilities located in module ezdxf.algebra:

from ezdxf.algebra import Vector

Functions

ezdxf.algebra.is_close(a, b)

Returns True if value is close to value b, uses math.isclose(a, b, abs_tol=1e-9) for Python 3, and emulates this function for Python 2.7.

ezdxf.algebra.is_close_points(p1, p2)

Returns True if all axis of p1 and p2 are close.

ezdxf.algebra.bspline_control_frame(fit_points, degree=3, method='distance', power=.5)

Generates the control points for the B-spline control frame by Curve Global Interpolation. Given are the fit points and the degree of the B-spline. The function provides 3 methods for generating the parameter vector t:

  1. method = uniform, creates a uniform t vector, form 0 to 1 evenly spaced; see uniform method
  2. method = distance, creates a t vector with values proportional to the fit point distances, see chord length method
  3. method = centripetal, creates a t vector with values proportional to the fit point distances^power; see centripetal method
Parameters:
  • fit_points – fit points of B-spline, as list of (x, y[, z]) tuples
  • degree – degree of B-spline
  • method – calculation method for parameter vector t
  • power – power for centripetal method
Returns:

a BSpline object, with BSpline.control_points containing the calculated control points, also BSpline.knot_values() returns the used knot values.

OCS Class

class ezdxf.algebra.OCS
OCS.__init__(extrusion=(0, 0, 1))

Establish an Object Coordinate System for a given extrusion vector.

OCS.to_wcs(point)

Calculate world coordinates for point in object coordinates.

OCS.points_to_wcs(points)

Translate multiple object coordinates into world coordinates (generator).

OCS.from_wcs(point)

Calculate object coordinates for point in world coordinates.

OCS.points_from_wcs(points)

Translate multiple world coordinates into object coordinates (generator).

See also

OCS

UCS Class

class ezdxf.algebra.UCS
UCS.__init__(origin=(0, 0, 0), ux=None, uy=None, uz=None)

Establish an User Coordinate System. The UCS is defined by the origin and two unit vectors for the x-, y- or z-axis, all axis n 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).

Normalization of unit vectors is not required.

Parameters:
  • origin – defines the UCS origin in world coordinates
  • ux – defines the UCS x-axis as vector in WCS
  • uy – defines the UCS y-axis as vector in WCS
  • uz – defines the UCS z-axis as vector in WCS
UCS.to_wcs(point)

Calculate world coordinates for point in UCS coordinates.

UCS.points_to_wcs(points)

Translate multiple user coordinates into world coordinates (generator).

UCS.to_ocs(point)

Calculate OCS coordinates for point in UCS coordinates.

OCS is defined by the z-axis of the UCS.

UCS.points_from_wcs(points)

Translate multiple user coordinates into OCS coordinates (generator).

OCS is defined by the z-axis of the UCS.

UCS.from_wcs(point)

Calculate UCS coordinates for point in world coordinates.

UCS.points_from_wcs(points)

Translate multiple world coordinates into user coordinates (generator).

UCS.from_x_axis_and_point_in_xy(origin, axis, point)

Returns an new UCS defined by the origin, the x-axis vector and an arbitrary point in the xy-plane. (static method)

Parameters:
  • origin – UCS origin as (x, y, z) tuple in WCS
  • axis – x-axis vector as (x, y, z) tuple in WCS
  • point – arbitrary point unlike the origin in the xy-plane as (x, y, z) tuple in WCS
UCS.from_x_axis_and_point_in_xz(origin, axis, point)

Returns an new UCS defined by the origin, the x-axis vector and an arbitrary point in the xz-plane. (static method)

Parameters:
  • origin – UCS origin as (x, y, z) tuple in WCS
  • axis – x-axis vector as (x, y, z) tuple in WCS
  • point – arbitrary point unlike the origin in the xz-plane as (x, y, z) tuple in WCS
UCS.from_y_axis_and_point_in_xy(origin, axis, point)

Returns an new UCS defined by the origin, the y-axis vector and an arbitrary point in the xy-plane. (static method)

Parameters:
  • origin – UCS origin as (x, y, z) tuple in WCS
  • axis – y-axis vector as (x, y, z) tuple in WCS
  • point – arbitrary point unlike the origin in the xy-plane as (x, y, z) tuple in WCS
UCS.from_y_axis_and_point_in_yz(origin, axis, point)

Returns an new UCS defined by the origin, the y-axis vector and an arbitrary point in the yz-plane. (static method)

Parameters:
  • origin – UCS origin as (x, y, z) tuple in WCS
  • axis – y-axis vector as (x, y, z) tuple in WCS
  • point – arbitrary point unlike the origin in the yz-plane as (x, y, z) tuple in WCS
UCS.from_z_axis_and_point_in_xz(origin, axis, point)

Returns an new UCS defined by the origin, the z-axis vector and an arbitrary point in the xz-plane. (static method)

Parameters:
  • origin – UCS origin as (x, y, z) tuple in WCS
  • axis – z-axis vector as (x, y, z) tuple in WCS
  • point – arbitrary point unlike the origin in the xz-plane as (x, y, z) tuple in WCS
UCS.from_z_axis_and_point_in_yz(origin, axis, point)

Returns an new UCS defined by the origin, the z-axis vector and an arbitrary point in the yz-plane. (static method)

Parameters:
  • origin – UCS origin as (x, y, z) tuple in WCS
  • axis – z-axis vector as (x, y, z) tuple in WCS
  • point – arbitrary point unlike the origin in the yz-plane as (x, y, z) tuple in WCS

See also

UCS

Vector

class ezdxf.algebra.Vector

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(), returns Vector(0, 0, 0)
  • Vector((x, y)), returns Vector(x, y, 0)
  • Vector((x, y, z)), returns Vector(x, y, z)
  • Vecotr(x, y), returns Vector(x, y, 0)
  • Vector(x, y, z), returns Vector(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)

Comparision between vectors and vectors to 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

Vector Attributes

Vector.x
Vector.y
Vector.z
Vector.xy

Returns Vector (x, y, 0)

Vector.xyz

Returns (x, y, z) tuple

Vector.magnitude

Returns length of vector

Vector.magnitude_square

Returns square length of vector

Vector.is_null

Returns True for Vector(0, 0, 0) else False

Vector.spatial_angle_rad

Returns spatial angle between vector and x-axis in radians

Vector.spatial_angle_deg

Returns spatial angle between vector and x-axis in degrees

Vector.angle_rad

Returns angle of vector in the xy-plane in radians.

Vector.angle_deg

Returns angle of vector in the xy-plane in degrees.

Vector Methods

Vector.generate(items)

Static method returns generator of Vector() objects created from items.

Vector.list(items)

Static method returns list of Vector() objects created from items.

Vector.from_rad_angle(angle, length=1.)

Static method returns Vector() from angle scaled by length, angle in radians.

Vector.from_deg_angle(angle, length=1.)

Static method returns Vector() from angle scaled by length, angle in degree.

Vector.__str__()

Return (x, y, z) as string.

Vector.__repr__()

Return Vector(x, y, z) as string.

Vector.__len__()

Returns always 3

Vector.__hash__()
Vector.copy()

Returns copy of vector.

Vector.__copy__()

Support for copy.copy().

Vector.__deepcopy__(memodict)

Support for copy.deepcopy().

Vector.__getitem__(index)

Support for indexing v[0] == v.x; v[1] == v.y; v[2] == v.z;

Vector.__iter__()

Support for the Python iterator protocol.

Vector.__abs__()

Returns length (magnitude) of vector.

Vector.orthogonal(ccw=True)

Returns orthogonal 2D vector, z value is unchanged.

Parameters:ccw – counter clockwise if True else clockwise
Vector.lerp(other, factor=.5)

Linear interpolation between vector and other, returns new Vector() object.

Parameters:
  • other – target vector/point
  • factor – interpolation factor (0==self, 1=other, 0.5=mid point)
Vector.project(other)

Project vector other onto self, returns new Vector() object.

Vector.normalize(length=1)

Returns new normalized Vector() object, optional scaled by length.

Vector.reversed()

Returns -vector as new Vector() object

Vector.__neg__()

Returns -vector as new Vector() object

Vector.__bool__()

Returns True if vector != (0, 0, 0)

Vector.__eq__(other)
Vector.__lt__(other)
Vector.__add__(other)
Vector.__radd__(other)
Vector.__sub__(other)
Vector.__rsub__(other)
Vector.__mul__(other)
Vector.__rmul__(other)
Vector.__truediv__(other)
Vector.__div__(other)
Vector.__rtruediv__(other)
Vector.__rdiv__(other)
Vector.dot(other)

Returns ‘dot’ product of vector . other.

Vector.cross(other)

Returns ‘cross’ product of vector x other

Vector.distance(other)

Returns distance between vector and other.

Vector.angle_between(other)

Returns angle between vector and other in th xy-plane in radians. +angle is counter clockwise orientation.

Vector.rot_z_rad(angle)

Return rotated vector around z axis, angle in radians.

Vector.rot_z_deg(angle)

Return rotated vector around z axis, angle in degrees.

Matrix44

class ezdxf.algebra.Matrix44

This is a pure Python implementation for 4x4 transformation matrices, to avoid dependency to big numerical packages like numpy, and before binary wheels, installation of these packages wasn’t always easy on Windows.

Matrix44 initialization:

  • Matrix44() is 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.
Matrix44.set(*args)

Reset 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.
Matrix44.__repr__()

Returns the representation string of the matrix:

Matrix44((col0, col1, col2, col3), (...), (...), (...))

Matrix44.get_row(row)

Get row as list of of four float values.

Matrix44.set_row(row, values)

Sets the values in a row.

Parameters:
  • row – row index [0..3]
  • values – four column values as iterable.
Matrix44.get_col(col)

Get column as list of of four float values.

Matrix44.set_col(col, values)

Sets the values in a column.

Parameters:
  • col – column index [0..3]
  • values – four column values as iterable.
Matrix44.copy()
Matrix44.__copy__()
Matrix44.scale(sx, sy=None, sz=None)

Class method returns a scaling transformation matrix. If sy is None, sy = sx, and if sz is None sz = sx.

Matrix44.translate(x, y, z)

Class method returns a translation matrix to (x, y, z).

Matrix44.x_rotate(angle)

Class method returns a rotation matrix about the x-axis.

Parameters:angle – rotation angle in radians
Matrix44.y_rotate(angle)

Class method returns a rotation matrix about the y-axis.

Parameters:angle – rotation angle in radians
Matrix44.z_rotate(angle)

Class method returns a rotation matrix about the z-axis.

param angle:rotation angle in radians
Matrix44.axis_rotate(axis, angle)

Class method returns a rotation matrix about an arbitrary axis.

Parameters:
  • axis – rotation axis as (x, y, z) tuple
  • angle – rotation angle in radians
Matrix44.xyz_rotate(angle_x, angle_y, angle_z)

Class method 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
Matrix44.perspective_projection(left, right, top, bottom, near, far)

Class method 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
Matrix44.perspective_projection_fov(fov, aspect, near, far)

Class method 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
Matrix44.chain(*matrices)

Compose a transformation matrix from one or more matrices.

Matrix44.__setitem__(coord, value)

Set (row, column) element.

Matrix44.__getitem__(coord)

Get (row, column) element.

Matrix44.__iter__()

Iterates over all matrix values.

Matrix44.__mul__(other)

Returns a new matrix as result of the matrix multiplication with another matrix.

Matrix44.__imul__(other)

Inplace multiplication with another matrix.

Matrix44.fast_mul(other)

Multiplies this matrix with other matrix inplace.

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 __imul__().

Matrix44.rows()

Iterate over rows as 4-tuples.

Matrix44.columns()

Iterate over columns as 4-tuples.

Matrix44.transform(vector)

Transforms a 3d vector and return the result as a tuple.

Matrix44.transform_vectors(vectors)

Returns a list of transformed vectors.

Matrix44.transpose()

Swaps the rows for columns inplace.

Matrix44.get_transpose()

Returns a new transposed matrix.

Matrix44.determinant()

Returns determinant.

Matrix44.inverse()

Returns the inverse of the matrix.

Raises:ZeroDivisionError – if matrix has no inverse.

BSpline

class ezdxf.algebra.BSpline

Calculate the vertices of a B-spline curve, using an uniform open knot vector (clamped curve).

BSpline.control_points

Control points as list of Vector objects

BSpline.count

Count of control points, (n + 1 in math definition).

BSpline.order

Order of B-spline = degree + 1

BSpline.degree

Degree (p) of B-spline = order - 1

BSpline.max_t

Max knot value.

BSpline.knot_values()

Returns a list of knot values as floats, the knot vector always has order+count values (n + p + 2 in math definition)

BSpline.basis_values(t)

Returns the basis vector for position t.

BSpline.approximate(segments)

Approximates the whole B-spline from 0 to max_t, by line segments as a list of vertices, vertices count = segments + 1

BSpline.point(t)

Returns the B-spline vertex at position t as (x, y[, z]) tuple.

BSplineU

class ezdxf.algebra.BSpline(BSpline)

Calculate the points of a B-spline curve, uniform (periodic) knot vector (open curve).

BSplineClosed

class ezdxf.algebra.BSplineClosed(BSplineU)

Calculate the points of a closed uniform B-spline curve (closed curve).

DBSpline

class ezdxf.algebra.DBSpline(BSpline)

Calculate points and derivative of a B-spline curve, using an uniform open knot vector (clamped curve).

DBSpline.point(t)

Returns the B-spline vertex, 1. derivative and 2. derivative at position t as tuple (vertex, d1, d2), each value is a (x, y, z) tuple.

DBSplineU

class ezdxf.algebra.DBSplineU(DBSpline)

Calculate points and derivative of a B-spline curve, uniform (periodic) knot vector (open curve).

DBSplineClosed

class ezdxf.algebra.DBSplineClosed(DBSplineU)

Calculate the points and derivative of a closed uniform B-spline curve (closed curve).