Forms

2D Forms

Basic 2D shapes as iterable of Vec3.

ezdxf.render.forms.box(sx: float = 1.0, sy: float = 1.0, center=False) → tuple[Vec3, Vec3, Vec3, Vec3]

Returns 4 vertices for a box with a width of sx by and a height of sy. The center of the box in (0, 0) if center is True otherwise the lower left corner is (0, 0), upper right corner is (sx, sy).

ezdxf.render.forms.circle(count: int, radius: float = 1, elevation: float = 0, close: bool = False) → Iterable[Vec3]

Create polygon vertices for a circle with the given radius and approximated by count vertices, elevation is the z-axis for all vertices.

Parameters:

  • count – count of polygon vertices

  • radius – circle radius

  • elevation – z-axis for all vertices

  • close – yields first vertex also as last vertex if True.

Returns:

vertices in counter-clockwise orientation as Vec3 objects

ezdxf.render.forms.ellipse(count: int, rx: float = 1, ry: float = 1, start_param: float = 0, end_param: float = math.tau, elevation: float = 0) → Iterable[Vec3]

Create polygon vertices for an ellipse with given rx as x-axis radius and ry as y-axis radius approximated by count vertices, elevation is the z-axis for all vertices. The ellipse goes from start_param to end_param in counter clockwise orientation.

Parameters:

  • count – count of polygon vertices

  • rx – ellipse x-axis radius

  • ry – ellipse y-axis radius

  • start_param – start of ellipse in range [0, 2π]

  • end_param – end of ellipse in range [0, 2π]

  • elevation – z-axis for all vertices

Returns:

vertices in counter clockwise orientation as Vec3 objects

ezdxf.render.forms.euler_spiral(count: int, length: float = 1, curvature: float = 1, elevation: float = 0) → Iterable[Vec3]

Create polygon vertices for an euler spiral of a given length and radius of curvature. This is a parametric curve, which always starts at the origin (0, 0).

Parameters:

  • count – count of polygon vertices

  • length – length of curve in drawing units

  • curvature – radius of curvature

  • elevation – z-axis for all vertices

Returns:

vertices as Vec3 objects

ezdxf.render.forms.gear(count: int, top_width: float, bottom_width: float, height: float, outside_radius: float, elevation: float = 0, close: bool = False) → Iterable[Vec3]

Returns the corner vertices of a gear shape (cogwheel).

Warning

This function does not create correct gears for mechanical engineering!

Parameters:

  • count – teeth count >= 3

  • top_width – teeth width at outside radius

  • bottom_width – teeth width at base radius

  • height – teeth height; base radius = outside radius - height

  • outside_radius – outside radius

  • elevation – z-axis for all vertices

  • close – yields first vertex also as last vertex if True.

Returns:

vertices in counter clockwise orientation as Vec3 objects

ezdxf.render.forms.ngon(count: int, length: float | None = None, radius: float | None = None, rotation: float = 0.0, elevation: float = 0.0, close: bool = False) → Iterable[Vec3]

Returns the corner vertices of a regular polygon. The polygon size is determined by the edge length or the circum radius argument. If both are given length has the higher priority.

Parameters:

  • count – count of polygon corners >= 3

  • length – length of polygon side

  • radius – circum radius

  • rotation – rotation angle in radians

  • elevation – z-axis for all vertices

  • close – yields first vertex also as last vertex if True.

Returns:

vertices as Vec3 objects

ezdxf.render.forms.square(size: float = 1.0, center=False) → tuple[Vec3, Vec3, Vec3, Vec3]

Returns 4 vertices for a square with a side length of the given size. The center of the square in (0, 0) if center is True otherwise the lower left corner is (0, 0), upper right corner is (size, size).

ezdxf.render.forms.star(count: int, r1: float, r2: float, rotation: float = 0.0, elevation: float = 0.0, close: bool = False) → Iterable[Vec3]

Returns the corner vertices for a star shape.

The shape has count spikes, r1 defines the radius of the “outer” vertices and r2 defines the radius of the “inner” vertices, but this does not mean that r1 has to be greater than r2.

Parameters:

  • count – spike count >= 3

  • r1 – radius 1

  • r2 – radius 2

  • rotation – rotation angle in radians

  • elevation – z-axis for all vertices

  • close – yields first vertex also as last vertex if True.

Returns:

vertices as Vec3 objects

ezdxf.render.forms.turtle(commands: str, start=Vec2(0, 0), angle: float = 0) → Iterator[Vec2]

Returns the 2D vertices of a polyline created by turtle-graphic like commands:

  • <length> - go <length> units forward in current direction and yield vertex

  • r<angle> - turn right <angle> in degrees, a missing angle is 90 deg

  • l<angle> - turn left <angle> in degrees, a missing angle is 90 deg

  • @<x>,<y> - go relative <x>,<y> and yield vertex

The command string "10 l 10 l 10" returns the 4 corner vertices of a square with a side length of 10 drawing units.

Parameters:

  • commands – command string, commands are separated by spaces

  • start – starting point, default is (0, 0)

  • angle – starting direction, default is 0 deg

3D Forms

Create 3D forms as MeshTransformer objects.

ezdxf.render.forms.cube(center: bool = True) → MeshTransformer

Create a cube as MeshTransformer object.

Parameters:

center – ‘mass’ center of cube, (0, 0, 0) if True, else first corner at (0, 0, 0)

Returns: MeshTransformer

ezdxf.render.forms.cone(count: int = 16, radius: float = 1.0, apex: UVec = (0, 0, 1), *, caps=True) → MeshTransformer

Create a cone as MeshTransformer object, the base center is fixed in the origin (0, 0, 0).

Parameters:

  • count – edge count of basis_vector

  • radius – radius of basis_vector

  • apex – tip of the cone

  • caps – add a bottom face as ngon if True

ezdxf.render.forms.cone_2p(count: int = 16, radius: float = 1.0, base_center: UVec = (0, 0, 0), apex: UVec = (0, 0, 1), *, caps=True) → MeshTransformer

Create a cone as MeshTransformer object from two points, base_center is the center of the base circle and apex as the tip of the cone.

Parameters:

  • count – edge count of basis_vector

  • radius – radius of basis_vector

  • base_center – center point of base circle

  • apex – tip of the cone

  • caps – add a bottom face as ngon if True

Raises:

ValueError – the cone orientation cannot be detected (base center == apex)

ezdxf.render.forms.cylinder(count: int = 16, radius: float = 1.0, top_radius: float | None = None, top_center: UVec = (0, 0, 1), *, caps=True) → MeshTransformer

Create a cylinder as MeshTransformer object, the base center is fixed in the origin (0, 0, 0).

Parameters:

  • count – profiles edge count

  • radius – radius for bottom profile

  • top_radius – radius for top profile, if None top_radius == radius

  • top_center – location vector for the center of the top profile

  • caps – close hull with top- and bottom faces (ngons)

ezdxf.render.forms.cylinder_2p(count: int = 16, radius: float = 1, base_center: UVec = (0, 0, 0), top_center: UVec = (0, 0, 1), *, caps=True) → MeshTransformer

Creates a cylinder as MeshTransformer object from two points, base_center is the center of the base circle and, top_center the center of the top circle.

Parameters:

  • count – cylinder profile edge count

  • radius – radius for bottom profile

  • base_center – center of base circle

  • top_center – center of top circle

  • caps – close hull with top- and bottom faces (ngons)

Raises:

ValueError – the cylinder orientation cannot be detected (base center == top center)

ezdxf.render.forms.helix(radius: float, pitch: float, turns: float, resolution: int = 16, ccw=True) → Iterator[Vec3]

Yields the vertices of a helix. The center of the helix is always (0, 0), a positive pitch value creates a helix along the +z-axis, a negative value along the -z-axis.

Parameters:

  • radius – helix radius

  • pitch – the height of one complete helix turn

  • turns – count of turns

  • resolution – vertices per turn

  • ccw – creates a counter-clockwise turning (right-handed) helix if True

ezdxf.render.forms.sphere(count: int = 16, stacks: int = 8, radius: float = 1, *, quads=True) → MeshTransformer

Create a sphere as MeshTransformer object, the center of the sphere is always at (0, 0, 0).

Parameters:

  • count – longitudinal slices

  • stacks – latitude slices

  • radius – radius of sphere

  • quads – use quadrilaterals as faces if True else triangles

ezdxf.render.forms.torus(major_count: int = 16, minor_count: int = 8, major_radius=1.0, minor_radius=0.1, start_angle: float = 0.0, end_angle: float = math.tau, *, caps=True) → MeshTransformer

Create a torus as MeshTransformer object, the center of the torus is always at (0, 0, 0). The major_radius has to be bigger than the minor_radius.

Parameters:

  • major_count – count of circles

  • minor_count – count of circle vertices

  • major_radius – radius of the circle center

  • minor_radius – radius of circle

  • start_angle – start angle of torus in radians

  • end_angle – end angle of torus in radians

  • caps – close hull with start- and end faces (ngons) if the torus is open

3D Form Builder

ezdxf.render.forms.extrude(profile: Iterable[UVec], path: Iterable[UVec], close=True, caps=False) → MeshTransformer

Extrude a profile polygon along a path polyline, the vertices of profile should be in counter-clockwise order. The sweeping profile will not be rotated at extrusion!

Parameters:

  • profile – sweeping profile as list of (x, y, z) tuples in counter-clockwise order

  • path – extrusion path as list of (x, y, z) tuples

  • close – close profile polygon if True

  • caps – close hull with top- and bottom faces (ngons)

Returns: MeshTransformer

ezdxf.render.forms.extrude_twist_scale(profile: Iterable[UVec], path: Iterable[UVec], *, twist: float = 0.0, scale: float = 1.0, step_size: float = 1.0, close=True, caps=False, quads=True) → MeshTransformer

Extrude a profile polygon along a path polyline, the vertices of profile should be in counter-clockwise order. This implementation can scale and twist the sweeping profile along the extrusion path. The path segment points are fix points, the max_step_size is used to create intermediate profiles between this fix points. The max_step_size is adapted for each segment to create equally spaced distances. The twist angle is the rotation angle in radians and the scale argument defines the scale factor of the final profile. The twist angle and scaling factor of the intermediate profiles will be linear interpolated between the start and end values.

Parameters:

  • profile – sweeping profile as list of (x, y, z) tuples in counter-clockwise order

  • path – extrusion path as list of (x, y, z) tuples

  • twist – rotate sweeping profile up to the given end rotation angle in radians

  • scale – scale sweeping profile gradually from 1.0 to given value

  • step_size – rough distance between automatically created intermediate profiles, the step size is adapted to the distances between the path segment points, a value od 0.0 disables creating intermediate profiles

  • close – close profile polygon if True

  • caps – close hull with top- and bottom faces (ngons)

  • quads – use quads for “sweeping” faces if True else triangles, the top and bottom faces are always ngons

Returns: MeshTransformer

ezdxf.render.forms.from_profiles_linear(profiles: Sequence[Sequence[Vec3]], *, close=True, quads=True, caps=False) → MeshTransformer

Returns a MeshTransformer instance from linear connected profiles.

Parameters:

  • profiles – list of profiles

  • close – close profile polygon if True

  • quads – use quadrilaterals as connection faces if True else triangles

  • caps – close hull with top- and bottom faces (ngons)

ezdxf.render.forms.from_profiles_spline(profiles: Sequence[Sequence[Vec3]], subdivide: int = 4, *, close=True, quads=True, caps=False) → MeshTransformer

Returns a MeshTransformer instance by spline interpolation between given profiles. Requires at least 4 profiles. A subdivide value of 4, means, create 4 face loops between two profiles, without interpolation two profiles create one face loop.

Parameters:

  • profiles – list of profiles

  • subdivide – count of face loops

  • close – close profile polygon if True

  • quads – use quadrilaterals as connection faces if True else triangles

  • caps – close hull with top- and bottom faces (ngons)

ezdxf.render.forms.rotation_form(count: int, profile: Iterable[UVec], angle: float = math.tau, axis: UVec = (1, 0, 0), *, caps=False) → MeshTransformer

Returns a MeshTransformer instance created by rotating a profile around an axis.

Parameters:

  • count – count of rotated profiles

  • profile – profile to rotate as list of vertices

  • angle – rotation angle in radians

  • axis – rotation axis

  • caps – close hull with start- and end faces (ngons)

ezdxf.render.forms.sweep(profile: Iterable[UVec], sweeping_path: Iterable[UVec], *, close=True, quads=True, caps=True) → MeshTransformer

Returns the mesh from sweeping a profile along a 3D path, where the sweeping path defines the final location in the WCS.

The profile is defined in a reference system. The origin of this reference system will be moved along the sweeping path where the z-axis of the reference system is pointing into the moving direction.

Returns the mesh as ezdxf.render.MeshTransformer object.

Parameters:

  • profile – sweeping profile defined in the reference system as iterable of (x, y, z) coordinates in counter-clockwise order

  • sweeping_path – the sweeping path defined in the WCS as iterable of (x, y, z) coordinates

  • close – close sweeping profile if True

  • quads – use quadrilaterals as connection faces if True else triangles

  • caps – close hull with top- and bottom faces (ngons)

ezdxf.render.forms.sweep_profile(profile: Iterable[UVec], sweeping_path: Iterable[UVec]) → list[Sequence[Vec3]]

Returns the intermediate profiles of sweeping a profile along a 3D path where the sweeping path defines the final location in the WCS.

The profile is defined in a reference system. The origin of this reference system will be moved along the sweeping path where the z-axis of the reference system is pointing into the moving direction.

Returns the start-, end- and all intermediate profiles along the sweeping path.