Forms¶
This module provides functions to create 2D and 3D forms as vertices or mesh objects.
2D Forms
3D Forms
3D Form Builder
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 vertexr<angle>
- turn right <angle> in degrees, a missing angle is 90 degl<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)
ifTrue
, 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 == radiustop_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 trianglescaps – 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 trianglescaps – 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 trianglescaps – 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.