Turtle

Turtles in a PowerShell

Turtle Graphics are a great way to learn programming and describe shapes.

Turtle graphics start really simple.

Imagine we are a turtle dragging a pen.

We can draw almost any shape by moving.

We can only really move in two ways:

We can turn, and we can take a step forward.

Turtle graphics starts with these two operations:

• Rotate() rotates the turtle
• Forward() moves forward

We can easily keep a list of these steps in memory, and draw them with SVG.

We can make Turtle in any language.

This module makes Turtle in PowerShell.

Installing and Importing

We can install Turtle from the PowerShell Gallery:

Install-Module Turtle -Scope CurrentUser -Force

Then we can import it like any other module

Import-Module Turtle -Force -PassThru

Cloning and Importing

You can also clone the repository and import the module

git clone https://github.com/PowerShellWeb/Turtle
cd ./Turtle
Import-Module ./ -Force -PassThru

Turtle GitHub Action

Turtle has a GitHub action, and can be run in a workflow.

To use the turtle action, simply refer to this repository:

- name: UseTurtle
  uses: StartAutomating/Turtle@main

This will run any *.turtle.ps1 files found in your repository, and check in any files that have changed.

What does this give us?

We Can Generate Turtle Graphics in GitHub Workflows

Getting Started

Once we've imported Turtle, we can create any number of turtles, and control them with commands and methods.

The turtle is represented as an object, and any number of commands can make or move turtles.

• New-Turtle created a turtle
• Move-Turtle performs a single turtle movement
• Set-Turtle changes the turtle's properties
• Save-Turtle saves the output of a turtle.

Last but not least: Get-Turtle lets you run multiple steps of turtle, and is aliased to urtle.

Drawing Squares

Let's start simple, by drawing a square with a series of commands.

New-Turtle | 
    Move-Turtle Forward 10 |
    Move-Turtle Rotate 90 |
    Move-Turtle Forward 10 |
    Move-Turtle Rotate 90 |
    Move-Turtle Forward 10 |
    Move-Turtle Rotate 90 |
    Move-Turtle Forward 10 |
    Move-Turtle Rotate 90 |
    Save-Turtle "./Square.svg"

We can also write this using a method chain:

$turtle = New-Turtle
$turtle.
    Forward(10).Rotate(90).
    Forward(10).Rotate(90).
    Forward(10).Rotate(90).
    Forward(10).Rotate(90).
    Symbol.Save("$pwd/Square.svg")

Or we could use a loop:

$turtle = New-Turtle
foreach ($n in 1..4) {
    $turtle = $turtle.Forward(10).Rotate(90)
}
$turtle | Save-Turtle ./Square.svg

Or we could use Get-Turtle directly.

turtle forward 10 rotate 90 forward 10 rotate 90 forward 10 rotate 90 forward 10 rotate 90 |
    Save-Turtle ./Square.svg

Or we could use Get-Turtle with a bit of PowerShell multiplication magic:

turtle ('forward',10,'rotate',90 * 4) |
    Save-Turtle ./Square.svg

This just demonstrates how we can construct shapes out of these two simple primitive steps.

There are a shell of a lot of ways you can draw any shape.

Turtle has many methods to help you draw, including a convenience method for squares.

So our shortest square can be written as:

turtle square 10 | Save-Turtle ./Square.svg

Drawing Other Shapes

We can use the same techniques to construct other shapes.

For example, this builds us a hexagon:

$turtle = New-Turtle

foreach ($n in 1..6) {
    $turtle = $turtle.Forward(10).Rotate(60)
}

$turtle | 
    Save-Turtle "./Hexagon.svg" 

Because this Turtle generates SVG, we can also use it to create patterns.

    turtle ('Forward', 10, 'Rotate', 60  * 6) | 
        Set-Turtle -Property Stroke '#4488ff' |
        Save-Turtle -Path ./Examples/HexagonPattern.svg -Property Pattern

Drawing Fractals

Turtle is often used to draw fractals.

Many fractals can be described in something called a L-System (short for Lindenmayer system)

L-Systems describe:

• An initial state (called an Axiom)
• A series of rewriting rules
• The way each variable should be interpreted.

For example, let's show how we contruct the Box Fractal

Our Axiom is F-F-F-F.

This should look familiar: it's a shorthand for the squares we drew earlier.

It basically reads "go forward, then left, four times"

Our Rule is F = 'F-F+F+F-F'.

This means every time we encounter F, we want to replace it with F-F+F+F-F.

This will turn our one box into 6 new boxes. If we repeat it again, we'll get 36 boxes. Once more and we're at 216 boxes.

Lets show the first three generations of the box fractal:

    Turtle BoxFractal 5 1 |
    Set-Turtle Stroke '#4488ff' |
    Save-Turtle ./Examples/BoxFractal1.svg



    Turtle BoxFractal 5 2 |
    Set-Turtle Stroke '#4488ff' |
    Save-Turtle ./Examples/BoxFractal2.svg



    Turtle BoxFractal 5 3 |
    Set-Turtle Stroke '#4488ff' |
    Save-Turtle ./Examples/BoxFractal3.svg

This implementation of Turtle has quite a few built-in fractals.

For example, here is an example of a pattern comprised of Koch Snowflakes:

    turtle KochSnowflake 2.5 4 |     
        Set-Turtle -Property StrokeWidth '0.1%' | 
        Set-Turtle -Property Stroke '#4488ff' | 
        Set-Turtle -Property PatternTransform -Value @{scale = 0.5 } |
        Save-Turtle -Path ./Examples/KochSnowflakePattern.svg -Property Pattern

We can also animate the pattern, for endless variety:

$turtle = turtle KochSnowflake 10 4 | 
    Set-Turtle -Property PatternTransform -Value @{scale=0.33} |
    set-turtle -property Fill -value '#4488ff' |
    Set-Turtle -Property PatternAnimation -Value ([Ordered]@{
        type = 'scale'    ; values = 0.66,0.33, 0.66 ; repeatCount = 'indefinite' ;dur = "23s"; additive = 'sum'
    }, [Ordered]@{
        type = 'rotate'   ; values = 0, 360 ;repeatCount = 'indefinite'; dur = "41s"; additive = 'sum'
    }, [Ordered]@{
        type = 'skewX'    ; values = -30,30,-30;repeatCount = 'indefinite';dur = "83s";additive = 'sum'
    }, [Ordered]@{
        type = 'skewY'    ; values = 30,-30, 30;repeatCount = 'indefinite';additive = 'sum';dur = "103s"
    }, [Ordered]@{
        type = 'translate';values = "0 0","42 42", "0 0";repeatCount = 'indefinite';additive = 'sum';dur = "117s"
    })    
    
$turtle | save-turtle -Path ./EndlessSnowflake.svg -Property Pattern
Pop-Location

Turtles in HTML

SVG is HTML.

So, because our Turtle is built atop of an SVG path, our Turtle is HTML.

Don't believe me? Try this?

turtle SierpinskiTriangle |
    Set-Turtle Stroke '#4488ff' | 
    Save-Turtle ./SierpinskiTriangle.html

Anything we do with our turtle should work within a webpage.

There are a few properties of the turtle that may be helpful:

• .Canvas returns the turtle rendered in an HTML canvas
• .OffsetPath returns the turtle as an offset path
• .ClipPath returns the turtle as a clip path

Turtles in Raster

Because our Turtle can be painted onto an HTML canvas, we can easily turn it into a raster format, like PNG.

This works by launching the browser in headless mode, rasterizing the image, and returning the bytes.

Any turtle can be saved as a PNG, JPEG, and WEBP.

turtle SierpinskiTriangle |
    Set-Turtle Stroke '#4488ff' | 
    Save-Turtle ./SierpinskiTriangle.png

Turtles are Cool

You should now have some sense of how cool Turtle graphics can be, and how easy it is to get stared.

Play around. Draw something. Please provide feedback by filing an issue or starting a discussion.

Open an issue if you want a new shape or fractal.

File a pull request if you have some cool changes to make.

Have fun!

Hope this helps!