Drawing

The drawing functions are distributed across the modules where they naturally live. Path generators return points; path renderers turn points into geometry.

Arc & catenary

pybosl2.shapes2d.arc(count=None, radius=None, angle=None, diameter=None, center=None, points=None, corner=None, width=None, thickness=None, start=None, wedge=False, long=False, clockwise=False, counterclockwise=False, endpoint=True, fn=None, fa=None, fs=None)[source]

Return a 2-D arc, returned as a Path2D of points (BOSL2’s arc()).

All of BOSL2’s 2-D arc specifications are supported (3-D arcs, which project onto a plane, are not):

  • arc(radius=, angle=, [start=], [center=]) – radius about center, sweeping angle degrees from start (or angle=[start, end] for an explicit range).

  • arc(width=, thickness=) – a circular segment starting and ending on the X axis.

  • arc(center=, points=[P0, P1]) – around center from P0 toward the direction of P1; the short way by default, or the long/clockwise/counterclockwise way.

  • arc(points=[P0, P1, P2]) – through three points, from P0 via P1 to P2.

  • arc(corner=[P0, P1, P2], radius=) – the fillet arc of radius tangent to both legs of the corner P0-P1-P2.

Set wedge=True to prepend the centre point, giving a closed pie/sector path. When count is omitted the point count follows OpenSCAD’s $fn/$fa/$fs rules, matching BOSL2.

Parameters:
count : int | None

number of points (default: from $fn/$fa/$fs)

radius : float | None

radius of the arc

diameter : float | None

diameter of the arc

angle : float | Sequence[float] | None

degrees to sweep from start, or [start, end]

center : Sequence[float] | None

centre point (default [0, 0])

points : Path2D | None

two points (with center) or three points the arc passes through

corner : Sequence[Sequence[float]] | None

three points; the arc is the radius fillet tangent to both legs

width : float | None

chord width for the width/thickness form

thickness : float | None

height of the circular segment for the width/thickness form

start : float | None

starting angle in degrees (default 0)

wedge : bool

prepend the centre point, producing a closed sector (default False)

long : bool

for the two-point form, take the long way / a given handedness

clockwise : bool

for the two-point form, take the long way / a given handedness

counterclockwise : bool

for the two-point form, take the long way / a given handedness

endpoint : bool

include the final point (default True)

fn : int | None

number of fragments for circle resolution. Omitted, the ambient use_defaults(fn=...) value applies; fn=0 opts back out to fa/fs.

fa : float | None

minimum fragment angle for circle resolution. Omitted, the ambient use_defaults(fa=...) value applies.

fs : float | None

minimum fragment size for circle resolution. Omitted, the ambient use_defaults(fs=...) value applies.

Returns:

A Path2D (closed when wedge is set).

Return type:

Path2D

classmethod Path2D.catenary(width, droop=None, sides=100, angle=None)[source]

Return the catenary (hanging-chain) curve of the given width, as a Path2D.

Give exactly one of droop (how far the middle hangs below the endpoints) or angle (the slope in degrees at the endpoints). The curve passes through [-width/2, 0] and [width/2, 0] and hangs downward (negative droop/angle flips it upward). This is BOSL2’s catenary().

Parameters:
width : float

horizontal distance between the endpoints (> 0)

droop : float | None

how far the midpoint hangs below the endpoints (give this or angle)

sides : int

number of points along the curve (default 100)

angle : float | None

endpoint slope in degrees, 0 < |angle| < 90 (give this or droop)

Return type:

Path2D

Examples

A hanging arch, stroked into a 2-mm ribbon and extruded into a wall:

from pybosl2 import Path2D

Path2D.catenary(width=80, droop=30).stroke(width=2).linear_extrude(height=6).show()
Loading 3-D preview…

⬇ Download STL mesh

Helix

pybosl2.path3d.Path3D.helix() — see the Paths reference for full documentation.

2-D Turtle

Drive the turtle with methods – one per command, each returning the turtle so calls chain – and take the path when you are done:

from pybosl2.turtle import Turtle2D

path = Turtle2D().set_length(40).set_arc_steps(24)
for _ in range(4):
    path.move().arc_left(radius=8)
path.points().stroke(width=3, closed=True).linear_extrude(height=4).show()
Loading 3-D preview…

⬇ Download STL mesh

The command objects still work, and are what the methods build underneath; hand a list of them to turtle2d() when you are generating a program rather than writing one.

class pybosl2.turtle.TurtleCommands[source]

Bases: object

A method per turtle command, each running it and returning the turtle (SPEC P-8).

Mixed into Turtle2D and Turtle3D; every method builds a TurtleCommand and hands it to that turtle’s run(), so the two spellings execute exactly the same code:

Turtle2D().move(40).arc_left(radius=8)                       # methods
turtle2d([TurtleCommand(TurtleCommandType.MOVE, size=40)])   # command objects

Examples

from pybosl2.turtle import Turtle2D

path = Turtle2D().set_length(40).set_arc_steps(24)
for _ in range(4):
    path.move().arc_left(radius=8)
path.points().stroke(width=3, closed=True).linear_extrude(height=4).show()
Loading 3-D preview…

⬇ Download STL mesh

run(commands, repeat=1)[source]

Execute commands; provided by the concrete turtle.

Parameters:
commands : Sequence[TurtleCommand]

The commands to run.

repeat : int

How many times to repeat them.

Return type:

Self

command(command)[source]

Run one TurtleCommand.

The escape hatch for the commands without a method of their own – the compound arcs, and anything built programmatically.

Parameters:
command : TurtleCommand

The command to run.

Returns:

This turtle, so calls chain.

Return type:

Self

add_length(value=None, **kwargs)

Add size to the default step length.

Runs TurtleCommandType.ADDLENGTH.

Parameters:
value : Any

The command’s size; None uses the turtle’s current default.

**kwargs : Any

Any other TurtleCommand field, e.g. angle= on an arc.

Returns:

This turtle, so calls chain.

Return type:

Any

arc_down(value=None, **kwargs)

Arc downward with the given radius (3-D only).

Runs TurtleCommandType.ARCDOWN.

Parameters:
value : Any

The command’s radius; None uses the turtle’s current default.

**kwargs : Any

Any other TurtleCommand field, e.g. angle= on an arc.

Returns:

This turtle, so calls chain.

Return type:

Any

arc_left(value=None, **kwargs)

Arc left with the given radius.

Runs TurtleCommandType.ARCLEFT.

Parameters:
value : Any

The command’s radius; None uses the turtle’s current default.

**kwargs : Any

Any other TurtleCommand field, e.g. angle= on an arc.

Returns:

This turtle, so calls chain.

Return type:

Any

arc_left_to(value=None, **kwargs)

Arc left until the heading reaches an absolute angle.

Runs TurtleCommandType.ARCLEFTTO.

Parameters:
value : Any

The command’s radius; None uses the turtle’s current default.

**kwargs : Any

Any other TurtleCommand field, e.g. angle= on an arc.

Returns:

This turtle, so calls chain.

Return type:

Any

arc_right(value=None, **kwargs)

Arc right with the given radius.

Runs TurtleCommandType.ARCRIGHT.

Parameters:
value : Any

The command’s radius; None uses the turtle’s current default.

**kwargs : Any

Any other TurtleCommand field, e.g. angle= on an arc.

Returns:

This turtle, so calls chain.

Return type:

Any

arc_right_to(value=None, **kwargs)

Arc right until the heading reaches an absolute angle.

Runs TurtleCommandType.ARCRIGHTTO.

Parameters:
value : Any

The command’s radius; None uses the turtle’s current default.

**kwargs : Any

Any other TurtleCommand field, e.g. angle= on an arc.

Returns:

This turtle, so calls chain.

Return type:

Any

arc_up(value=None, **kwargs)

Arc upward with the given radius (3-D only).

Runs TurtleCommandType.ARCUP.

Parameters:
value : Any

The command’s radius; None uses the turtle’s current default.

**kwargs : Any

Any other TurtleCommand field, e.g. angle= on an arc.

Returns:

This turtle, so calls chain.

Return type:

Any

down(value=None, **kwargs)

Pitch down by angle degrees (3-D only).

Runs TurtleCommandType.DOWN.

Parameters:
value : Any

The command’s angle; None uses the turtle’s current default.

**kwargs : Any

Any other TurtleCommand field, e.g. angle= on an arc.

Returns:

This turtle, so calls chain.

Return type:

Any

jump(value=None, **kwargs)

Jump to an absolute position without drawing.

Runs TurtleCommandType.JUMP.

Parameters:
value : Any

The command’s size; None uses the turtle’s current default.

**kwargs : Any

Any other TurtleCommand field, e.g. angle= on an arc.

Returns:

This turtle, so calls chain.

Return type:

Any

left(value=None, **kwargs)

Turn left by angle degrees (default: the current turn angle).

Runs TurtleCommandType.LEFT.

Parameters:
value : Any

The command’s angle; None uses the turtle’s current default.

**kwargs : Any

Any other TurtleCommand field, e.g. angle= on an arc.

Returns:

This turtle, so calls chain.

Return type:

Any

move(value=None, **kwargs)

Move forward by size (default: the current step length).

Runs TurtleCommandType.MOVE.

Parameters:
value : Any

The command’s size; None uses the turtle’s current default.

**kwargs : Any

Any other TurtleCommand field, e.g. angle= on an arc.

Returns:

This turtle, so calls chain.

Return type:

Any

right(value=None, **kwargs)

Turn right by angle degrees (default: the current turn angle).

Runs TurtleCommandType.RIGHT.

Parameters:
value : Any

The command’s angle; None uses the turtle’s current default.

**kwargs : Any

Any other TurtleCommand field, e.g. angle= on an arc.

Returns:

This turtle, so calls chain.

Return type:

Any

roll(value=None, **kwargs)

Roll about the heading by angle degrees (3-D only).

Runs TurtleCommandType.ROLL.

Parameters:
value : Any

The command’s angle; None uses the turtle’s current default.

**kwargs : Any

Any other TurtleCommand field, e.g. angle= on an arc.

Returns:

This turtle, so calls chain.

Return type:

Any

scale_length(value=None, **kwargs)

Multiply the default step length by size.

Runs TurtleCommandType.SCALE.

Parameters:
value : Any

The command’s size; None uses the turtle’s current default.

**kwargs : Any

Any other TurtleCommand field, e.g. angle= on an arc.

Returns:

This turtle, so calls chain.

Return type:

Any

set_angle(value=None, **kwargs)

Set the default turn angle for later turns.

Runs TurtleCommandType.ANGLE.

Parameters:
value : Any

The command’s angle; None uses the turtle’s current default.

**kwargs : Any

Any other TurtleCommand field, e.g. angle= on an arc.

Returns:

This turtle, so calls chain.

Return type:

Any

set_arc_steps(value=None, **kwargs)

Set the segment count for later arcs (0 = automatic).

Runs TurtleCommandType.ARCSTEPS.

Parameters:
value : Any

The command’s steps; None uses the turtle’s current default.

**kwargs : Any

Any other TurtleCommand field, e.g. angle= on an arc.

Returns:

This turtle, so calls chain.

Return type:

Any

set_direction(value=None, **kwargs)

Point the turtle along a direction vector.

Runs TurtleCommandType.SETDIR.

Parameters:
value : Any

The command’s size; None uses the turtle’s current default.

**kwargs : Any

Any other TurtleCommand field, e.g. angle= on an arc.

Returns:

This turtle, so calls chain.

Return type:

Any

set_length(value=None, **kwargs)

Set the default step length for later moves.

Runs TurtleCommandType.LENGTH.

Parameters:
value : Any

The command’s size; None uses the turtle’s current default.

**kwargs : Any

Any other TurtleCommand field, e.g. angle= on an arc.

Returns:

This turtle, so calls chain.

Return type:

Any

until_x(value=None, **kwargs)

Move along the heading until X reaches size.

Runs TurtleCommandType.UNTILX.

Parameters:
value : Any

The command’s size; None uses the turtle’s current default.

**kwargs : Any

Any other TurtleCommand field, e.g. angle= on an arc.

Returns:

This turtle, so calls chain.

Return type:

Any

until_y(value=None, **kwargs)

Move along the heading until Y reaches size.

Runs TurtleCommandType.UNTILY.

Parameters:
value : Any

The command’s size; None uses the turtle’s current default.

**kwargs : Any

Any other TurtleCommand field, e.g. angle= on an arc.

Returns:

This turtle, so calls chain.

Return type:

Any

until_z(value=None, **kwargs)

Move along the heading until Z reaches size (3-D only).

Runs TurtleCommandType.UNTILZ.

Parameters:
value : Any

The command’s size; None uses the turtle’s current default.

**kwargs : Any

Any other TurtleCommand field, e.g. angle= on an arc.

Returns:

This turtle, so calls chain.

Return type:

Any

up(value=None, **kwargs)

Pitch up by angle degrees (3-D only).

Runs TurtleCommandType.UP.

Parameters:
value : Any

The command’s angle; None uses the turtle’s current default.

**kwargs : Any

Any other TurtleCommand field, e.g. angle= on an arc.

Returns:

This turtle, so calls chain.

Return type:

Any

x_jump(value=None, **kwargs)

Jump to an absolute X, keeping the other coordinates.

Runs TurtleCommandType.XJUMP.

Parameters:
value : Any

The command’s size; None uses the turtle’s current default.

**kwargs : Any

Any other TurtleCommand field, e.g. angle= on an arc.

Returns:

This turtle, so calls chain.

Return type:

Any

x_move(value=None, **kwargs)

Move along +X by size, leaving the heading alone.

Runs TurtleCommandType.XMOVE.

Parameters:
value : Any

The command’s size; None uses the turtle’s current default.

**kwargs : Any

Any other TurtleCommand field, e.g. angle= on an arc.

Returns:

This turtle, so calls chain.

Return type:

Any

y_jump(value=None, **kwargs)

Jump to an absolute Y, keeping the other coordinates.

Runs TurtleCommandType.YJUMP.

Parameters:
value : Any

The command’s size; None uses the turtle’s current default.

**kwargs : Any

Any other TurtleCommand field, e.g. angle= on an arc.

Returns:

This turtle, so calls chain.

Return type:

Any

y_move(value=None, **kwargs)

Move along +Y by size, leaving the heading alone.

Runs TurtleCommandType.YMOVE.

Parameters:
value : Any

The command’s size; None uses the turtle’s current default.

**kwargs : Any

Any other TurtleCommand field, e.g. angle= on an arc.

Returns:

This turtle, so calls chain.

Return type:

Any

z_jump(value=None, **kwargs)

Jump to an absolute Z, keeping the other coordinates (3-D only).

Runs TurtleCommandType.ZJUMP.

Parameters:
value : Any

The command’s size; None uses the turtle’s current default.

**kwargs : Any

Any other TurtleCommand field, e.g. angle= on an arc.

Returns:

This turtle, so calls chain.

Return type:

Any

z_move(value=None, **kwargs)

Move along +Z by size, leaving the heading alone (3-D only).

Runs TurtleCommandType.ZMOVE.

Parameters:
value : Any

The command’s size; None uses the turtle’s current default.

**kwargs : Any

Any other TurtleCommand field, e.g. angle= on an arc.

Returns:

This turtle, so calls chain.

Return type:

Any

pybosl2.turtle.turtle2d(commands, state=None, repeat=1)[source]

Build a 2-D path from TurtleCommand objects — BOSL2’s turtle2d().

Creates a Turtle2D, runs commands (optionally repeat times), and returns the turtle. Access the path via Turtle2D.points() or the state via Turtle2D.full_state().

Parameters:
commands : Sequence[TurtleCommand]

A flat list of TurtleCommand objects.

state : Turtle2DState | None

Optional starting Turtle2DState.

repeat : int

Number of times to repeat the command list.

Returns:

The Turtle2D instance after executing all commands.

Return type:

Turtle2D

Examples

A rounded-corner square drawn with arcs:

from pybosl2.turtle import turtle2d
from pybosl2.points import Point
from pybosl2.turtle import TurtleCommand, TurtleCommandType as Tct

path = turtle2d([
    TurtleCommand(Tct.MOVE, size=40),
    TurtleCommand(Tct.ARCLEFT, radius=8),
    TurtleCommand(Tct.MOVE, size=40),
    TurtleCommand(Tct.ARCLEFT, radius=8),
    TurtleCommand(Tct.MOVE, size=40),
    TurtleCommand(Tct.ARCLEFT, radius=8),
    TurtleCommand(Tct.MOVE, size=40),
    TurtleCommand(Tct.ARCLEFT, radius=8),
]).points()
path.stroke(width=3, closed=True).linear_extrude(height=4).show()
Loading 3-D preview…

⬇ Download STL mesh

3-D Turtle

The 3-D turtle takes the same commands and the same methods; it is documented in Turtle (3-D).

Stroke & dashed stroke

Both 2-D and 3-D paths carry stroke and dashed_stroke as methods:

  • pybosl2.path2d.Path2D.stroke() / pybosl2.path2d.Path2D.dashed_stroke()

  • pybosl2.path3d.Path3D.stroke() / pybosl2.path3d.Path3D.dashed_stroke()

Coverage of BOSL2 drawing.scad

BOSL2 function

Status

Notes

arc

ported

arc() returns a Path2D; all 2-D forms (radius/angle, angle=[start, end], width/thickness, two-point with long/cw/ccw, three-point, corner=, and wedge=). 3-D arcs are not ported.

catenary

ported

catenary() — by droop= or endpoint angle=.

helix

ported

helix() — returns a Path3D (conical/flat spirals included).

turtle

ported

Turtle2D (methods) or turtle2d() (command objects) — the full command set, including repeat and the arcleft/arcright/arcleftto/arcrightto arcs.

stroke

ported

stroke() / stroke() — 2-D (segment rects + joints & endcaps) and 3-D (cylinder tube + spherical joints + revolved endcaps). Every BOSL2 endcap/joint style is generated directly: round, square, butt, dot, block, diamond, chisel, line, x, cross, arrow, arrow2, arrow3, tail, tail2 (arrow caps trim the line back). Per-vertex width lists and the *_angle/*_color knobs are not ported.

dashed_stroke

ported

dashed_stroke() / dashed_stroke() — the method forms that build unioned dash solids directly.

turtle3d

ported

Turtle (3-D) — the 3-D turtle as a Turtle3D class with the full simple and compound command sets.

debug_polygon / debug_region

not ported

annotated debugging modules (vertex/edge labels); no geometry payload.