Turtle

Turtle-style step language to generate coordinate points for polygon construction.. More...

Collaboration diagram for Turtle:

Files
file	turtle_path.scad
	Turtle-style step language to generate coordinate points for polygon construction.

Functions and/or Modules
function	polygon_turtle_path_p (s, p0=origin2d, h=0, m=0, _s_n=0, _p0_g)
	Interprets a turtle-style step language to generate coordinate points for polygon construction. More...

Usage Details

Turtle-style step language to generate coordinate points for polygon construction..

Requires:
include <omdl-base.scad>;
include <tools/2d/turtle_path.scad>;

Function and/or Module Documentation

polygon_turtle_path_p()

function polygon_turtle_path_p	(	s	,
		p0	= origin2d,
		h	= 0,
		m	= 0,
		_s_n	= 0,
		_p0_g
	)

Interprets a turtle-style step language to generate coordinate points for polygon construction.

Parameters

s	<datastruct> The list of steps.
p0	<point-2d> The initial coordinate [x, y].
h	<decimal> The current heading in degrees; 0 = positive x-axis, positive angles rotate counter-clockwise.
m	<integer> The return mode. When 0 (default), returns a <point-2d-list>. When 1, returns [point-2d-list, decimal] where the second element is the final heading after all steps have been evaluated.
_s_n	<integer> The current step number.
_p0_g	<point-2d> The global origin coordinate [x, y].

Returns

(1) <point-2d-list> when m is 0; (2) <datastruct> [point-2d-list, decimal] when m is 1.

The returned list contains the coordinate points of the path described in the list of steps s. When m is 1 the final heading is appended as the second element of the returned pair.

This function is a lightweight interpreter that converts a list of operation steps into coordinate points for polygon construction. It provides a convenient mechanism for defining polygons using a compact, step-based notation inspired by the Turtle graphics geometric drawing language. Each step produces one or more output points according to the schema described below.

Data structure schema:

name	schema
s	[ step, step, ..., step ]
step	[ operation, arg1, arg2, arg3, arg4 ]

Operations

The following table summarizes the supported operations, arguments, and their semantics.

operation	short	arguments		output coordinate point(s)
		minimum arguments	extended arguments
heading operations
turn_left	tl	a		(none)
turn_right	tr	a		(none)
line operations
close	cl	(none)	wc, fn	_p0_g
goto_xy	gxy	x, y	x, y, wc, fn	[x, y]
goto_x	gx	x	x, wc, fn	[x, p0.y]
goto_y	gy	y	y, wc, fn	[p0.x, y]
delta_xy	dxy	x, y	x, y, wc, fn	p0 + [x, y]
delta_x	dx	x	x, wc, fn	p0 + [x, 0]
delta_y	dy	y	y, wc, fn	p0 + [0, y]
delta_xa	dxa	x, a	x, a, wc, fn	p0 + [ x, x * tan(a) ]
delta_ya	dya	y, a	y, a, wc, fn	p0 + [ y / tan(a), y ]
move_ar	mar	m, a	m, a, wc, fn	p0 + line(m, a)
move_rr	mrr	m, a	m, a, wc, fn	p0 + line(m, h+a)
move_fw	mfw	m	m, wc, fn	p0 + line(m, h)
arc operations
arc_fw	afw	r, a	r, a, [o], fn	(see below)
arc_pv	apv	c, v, cw, fn		(see below)
arc_vv	avv	v, v, cw, fn		(see below)
arc_blend	ab	p2, p3, r	p2, p3, r, fn	(see below)
curve operations
bezier	bz	ctrl_pts	ctrl_pts, [o], fn	(see below)
spline	spl	knots	knots, [o], fn	(see below)
sub-step operations
repeat	rpt	steps	steps, n	(see below)
repeat_mx	rptmx	steps, axis	steps, axis, [o]	(see below)
repeat_my	rptmy	steps, axis	steps, axis, [o]	(see below)
transform	xfrm	steps, r	steps, r, t, mn, [o]	(see below)
point operations
path_p	pp	[p1, p2, ..., pn]		(see below)

The two argument columns divide the minimum form from the extended form: the left column shows the minimum required arguments, and the right column shows the extended form with additional optional parameters.

Some operations may generate either straight or periodic waveform lines. When a periodic waveform line is desired, additional parameters specify the waveform configuration and period fragment count as shown in the table above.

Wave-line waveform configuration

e	data type	default value	parameter description
*	datastruct	required	wc : waveform configuration [p, a, w, m]
*	integer		fn : number of facets; optional

wc

e	data type	default value	parameter description
0	decimal	see below	p : period length
1	decimal-list-3 | decimal	see below	a : amplitude configuration
2	datastruct | integer	see below	w : waveform shape configuration
3	datastruct | integer	see below	m : time-axis remapping mode configuration

Wave-line constructs a line with periodic waveform lateral displacement to the next point using polygon_line_wave_p(). See its documentation for more details and default value. All line operations accept the optional wc and fn parameters to produce a wave-line in place of a straight segment.

Heading operations

turn_left

Rotates the current heading counter-clockwise by a degrees. Produces no output coordinate points; only the heading h is updated for subsequent steps.

turn_right

Rotates the current heading clockwise by a degrees. Produces no output coordinate points; only the heading h is updated for subsequent steps.

Line operations

close

Closes the path by returning to the global origin _p0_g with a straight or wave-line segment. When no arguments are given, a straight line is drawn. The global origin is set automatically on the first step and remains fixed for the lifetime of the recursion.

goto_xy

Moves to the absolute coordinate [x, y], ignoring the current position.

goto_x

Moves to the absolute x-axis coordinate x, retaining the current y-axis coordinate.

goto_y

Moves to the absolute y-axis coordinate y, retaining the current x-axis coordinate.

delta_xy

Moves from the current position by the relative offset [x, y].

delta_x

Moves from the current position by the relative x-axis offset x, with no y-axis displacement.

delta_y

Moves from the current position by the relative y-axis offset y, with no x-axis displacement.

delta_xa

e	data type	default value	parameter description
0	decimal	required	x : x-axis displacement
1	decimal	required	a : angle in degrees from the x-axis

Moves from the current position by the relative offset [x, x * tan(a)], where the y-axis displacement is derived from the x-axis displacement x and the angle a. This is convenient when the horizontal extent of a step is known and the slope angle is the natural constraint.

delta_ya

e	data type	default value	parameter description
0	decimal	required	y : y-axis displacement
1	decimal	required	a : angle in degrees from the x-axis

Moves from the current position by the relative offset [y / tan(a), y], where the x-axis displacement is derived from the y-axis displacement y and the angle a. This is the complement of delta_xa and is convenient when the vertical extent of a step is known and the slope angle is the natural constraint.

move_ar

e	data type	default value	parameter description
0	decimal	required	m : radial distance
1	decimal	required	a : absolute angle in degrees

Moves from the current position by distance m at the absolute angle a, measured from the positive x-axis. The heading h is not consulted.

move_rr

e	data type	default value	parameter description
0	decimal	required	m : radial distance
1	decimal	required	a : angle offset in degrees relative to current heading

Moves from the current position by distance m at an angle of h + a, where h is the current heading. When a is zero this operation is equivalent to move_fw.

move_fw

Moves forward from the current position by distance m along the current heading h. Equivalent to move_rr with a set to zero.

Arc operations

arc_fw

e	data type	default value	parameter description
0	decimal	required	r : arc radius; must be positive
1	decimal	required	a : signed sweep angle in degrees; positive = CCW (left turn), negative = CW (right turn)
2	datastruct		[o] : options [update_heading]; optional; assign undef to accept all option defaults when only fn is needed
3	integer		fn : number of facets; optional

arc_fw[2]: o

e	data type	default value	parameter description
0	boolean	true	update_heading : when true the heading is advanced by a degrees on exit; when false the entry heading h is restored

Sweeps an arc of radius r through the signed angle a starting from the current position p0 and following the current heading h. The arc center lies perpendicular to h at distance r: to the left (h + 90°) when a is positive and to the right (h - 90°) when a is negative. The arc is delegated to polygon_arc_sweep_p(). Returns empty_lst when a is zero. By default the heading is updated to h + a on exit, so chained arc_fw steps flow naturally without manual heading bookkeeping. Pass [o] = [false] to suppress the heading update. Pass [o] = undef to accept all option defaults while still supplying fn.

arc_pv

e	data type	default value	parameter description
0	point-2d	required	c : arc center point [x, y]
1	point-2d | decimal	required	v : arc stop angle [x, y] or a
2	boolean	required	cw : arc sweep direction
3	integer		fn : the number of facets; optional

This operation constructs an arc about a center point specified as a coordinate. The arc begins at the angle defined by the vector [c, p0] and ends at the angle defined by either the vector [c, v] or by the scalar angle v (in degrees). The sweep direction is controlled by cw; when cw is set to true, the arc is swept clockwise from the start angle to the stop angle. The optional parameter fn specifies the number of facets and, when omitted, is determined automatically by get_fn().

arc_vv

e	data type	default value	parameter description
0	decimal-list-2	required	c : arc center point [m, a]
1	point-2d | decimal	required	v : arc stop angle [x, y] or a
2	boolean	required	cw : arc sweep direction
3	integer		fn : number of facets; optional

This operation constructs an arc about a center point specified as a vector [m, a] originating from the current position. The arc begins at the angle defined by the vector [c, p0] and ends at the angle defined by either the vector [c, v] or by the scalar angle v (in degrees). The sweep direction is controlled by cw; when cw is set to true, the arc is swept clockwise from the start angle to the stop angle. The optional parameter fn specifies the number of facets and, when omitted, is determined automatically by get_fn().

arc_blend

e	data type	default value	parameter description
0	point-2d	required	p2 : corner vertex coordinate [x, y]; the point where the two segments meet
1	point-2d	required	p3 : end point of the outgoing segment [x, y]
2	decimal	required	r : blend radius; must be positive
3	integer		fn : number of facets; optional

Replaces the sharp corner at p2 with a circular arc of radius r that is tangent to both the incoming segment [p0, p2] and the outgoing segment [p2, p3]. The current position p0 supplies the start point of the incoming segment. Only the arc points are emitted; the corner vertex p2 is not included. Delegates to polygon_arc_blend_p(). The heading h is not updated by this operation.

Curve operations

bezier

e	data type	default value	parameter description
0	point-2d-list	required	ctrl_pts : Bézier control point list [[x, y], ...]
1	datastruct		[o] : options [prepend_p0]; optional; assign undef to accept all option defaults when only fn is needed
2	integer		fn : number of facets; optional

bezier[1]: o

e	data type	default value	parameter description
0	boolean	true	prepend_p0 : when true the current position p0 is automatically prepended to ctrl_pts as the first control point

Evaluates a degree-n Bézier curve defined by the control point list ctrl_pts using the de Casteljau algorithm. When prepend_p0 is true (the default) the current position p0 is inserted as the first control point so the curve departs smoothly from the last emitted point. Pass [o] = [false] when ctrl_pts already contains the intended start point. Pass [o] = undef to accept all option defaults while still supplying fn. The heading h is not updated by this operation. Delegates to polygon_bezier_p().

spline

e	data type	default value	parameter description
0	point-2d-list	required	knots : Catmull-Rom knot list [[x, y], ...]
1	datastruct		[o] : options [prepend_p0, closed]; optional; assign undef to accept all option defaults when only fn is needed
2	integer		fn : facets per segment; optional

spline[1]: o

e	data type	default value	parameter description
0	boolean	true	prepend_p0 : when true the current position p0 is automatically prepended to knots as the first knot
1	boolean	false	closed : when true a closing segment is added from the last knot back to the first knot

Evaluates a centripetal Catmull-Rom spline through the knot list knots. The curve passes through every knot point. When prepend_p0 is true (the default) the current position p0 is inserted as the first knot so the spline departs from the last emitted point. When closed is true a closing segment from the last knot back to the first is included. Pass [o] = undef to accept all option defaults while still supplying fn. The heading h is not updated by this operation. Delegates to polygon_spline_p().

Sub-step operations

repeat

e	data type	default value	parameter description
0	datastruct	required	steps : sub-step list
1	integer	1	n : number of repetitions; optional

Evaluates the sub-step list steps n times in sequence. Each iteration begins where the previous left off, carrying p0, h, and _p0_g forward between iterations. The heading evolved inside the sub-steps carries back into the outer step list after all iterations complete. When n is omitted the sub-steps are evaluated once, making repeat useful as a plain grouping mechanism. Nesting is supported to arbitrary depth.

repeat_mx

e	data type	default value	parameter description
0	datastruct	required	steps : sub-step list
1	decimal	0	axis : scalar offset of the mirror axis from p0 along the y-axis; optional
2	datastruct		o : options [reverse, heading, mirror_start]; optional

repeat_mx[2]: o

e	data type	default value	parameter description
0	boolean	true	reverse : reverse the mirrored point list for correct polygon winding
1	boolean	true	heading : when true, carry the final heading of the forward pass back into the outer step list; when false, restore the entry heading
2	boolean	true	mirror_start : begin the mirrored pass from p0; when false, begin from the end of the forward pass

Evaluates steps once to produce a forward point list, then mirrors all output points about a horizontal axis at p0.y + axis. The mirrored list is appended after the forward list to produce a top-bottom symmetric profile in a single operation. The options bundle o controls winding order, heading continuity, and the start point of the mirrored pass. Nesting is supported to arbitrary depth.

repeat_my

e	data type	default value	parameter description
0	datastruct	required	steps : sub-step list
1	decimal	0	axis : scalar offset of the mirror axis from p0 along the x-axis; optional
2	datastruct		o : options [reverse, heading, mirror_start]; optional

repeat_my[2]: o

e	data type	default value	parameter description
0	boolean	true	reverse : reverse the mirrored point list for correct polygon winding
1	boolean	true	heading : when true, carry the final heading of the forward pass back into the outer step list; when false, restore the entry heading
2	boolean	true	mirror_start : begin the mirrored pass from p0; when false, begin from the end of the forward pass

Evaluates steps once to produce a forward point list, then mirrors all output points about a vertical axis at p0.x + axis. The mirrored list is appended after the forward list to produce a left-right symmetric profile in a single operation. The options bundle o controls winding order, heading continuity, and the start point of the mirrored pass. Nesting is supported to arbitrary depth.

transform

e	data type	default value	parameter description
0	datastruct	required	steps : sub-step list
1	decimal	required	r : rotation angle in degrees, applied about p0
2	point-2d	[0, 0]	t : translation vector [x, y]; optional
3	vector-2d	undef	mn : mirror normal vector [nx, ny]; applied before rotation; optional
4	datastruct		o : options [update_p0, update_h]; optional

transform[4]: o

e	data type	default value	parameter description
0	boolean	false	update_p0 : when true, advance the parent p0 to the last transformed point after the operation
1	boolean	o[0]	update_h : when true, update the parent h to h_final + r after the operation; defaults to update_p0 when not specified

Evaluates steps to produce a point list, then applies a 2D affine transformation to every output point via transform_p(). Mirror mn is applied first about the entry position p0, followed by rotation r about p0, then translation t. When mn is undef no mirror is applied. When both options are false (the default) the parent p0 and h are unchanged after the operation, making transform a pure geometric post-processor. update_p0 and update_h may be set independently: for example, pass [true, false] to advance p0 to the last transformed point while preserving the entry heading, or [false, true] to carry the rotated heading forward while keeping the turtle anchored at its entry position. When only update_p0 is supplied (e.g. [true]), update_h inherits the same value. Nesting is supported to arbitrary depth.

Point operations

path_p

e	data type	default value	parameter description
0	point-2d-list	required	path list of 2d points

Inserts a list of 2D points [x, y] into the output at the current step, specified as a single argument containing the point list. Care should be taken to ensure a smooth transition between the end of the previous step and the start of the inserted points.

Motor mount plate design example script

    include <omdl-base.scad>;
    include <tools/2d/turtle_path.scad>;
 
    $fn=36;
 
    h1 = 7.5;   h2 = 5;     h3 = 7.5;
    w1 = 5;     w2 = 20;    w3 = 5;
    r1 = 5;     r2 = 1/2;   rr = 1;
 
    sm =
    [
      ["delta_y",  h1],
      ["delta_x",  w1],
      ["delta_y",  h2],
      ["delta_xy", w3, h3],
      ["delta_x",  w1+w2-w3*2],
      ["delta_xy", w3, -h3],
      ["goto_y",   0],
      ["goto_x",   0],
    ];
 
    // convert the step moves into coordinates
    pp = polygon_turtle_path_p( sm );
 
    // round all of the vertices
    rp = polygon_round_eve_all_p( pp, rr );
 
    difference()
    {
      polygon( rp );
 
      c = [w1+w2/2+r1/2, h1+h2/2];
      translate(c) circle(r=r1);
      for(x=[-1,1], y=[-1,1]) translate(c+[x,y]*r1) circle(r=r2);
    }
 
    // end_include

Motor mount plate design example diagram

top	diag

The corners of this example 2d design plate have been rounded with the library function polygon_round_eve_all_p().