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

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

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 == v.x; v == v.y; v == 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).