README.md.ps1
|
<# .SYNOPSIS Turtle Graphics in PowerShell .EXAMPLE .\README.md.ps1 > .\README.md #> #requires -Module Turtle param() #region Introduction @" # Turtle <div align='center'> <img src='./Examples/SierpinskiTriangle.svg' alt='SierpinskiTriangle' width='50%' /> <br/> <a href='https://www.powershellgallery.com/packages/Turtle/' > <img src='https://img.shields.io/powershellgallery/dt/Turtle' /> </a> </div> ## Turtles in a PowerShell [Turtle Graphics](https://en.wikipedia.org/wiki/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](https://developer.mozilla.org/en-US/docs/Web/SVG). We can make Turtle in any language. This module makes Turtle in PowerShell. "@ #endregion Introduction #region Installation @" ### Installing and Importing We can install Turtle from the PowerShell Gallery: ~~~PowerShell $({Install-Module Turtle -Scope CurrentUser -Force}) ~~~ Then we can import it like any other module ~~~PowerShell $({Import-Module Turtle -Force -PassThru}) ~~~ #### Cloning and Importing You can also clone the repository and import the module ~~~PowerShell $({ git clone https://github.com/PowerShellWeb/Turtle cd ./Turtle Import-Module ./ -Force -PassThru }) ~~~ "@ #endregion Installation #region Turtle PowerShell GitHub Action @" ### 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: ~~~yaml - 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** "@ #endregion Turtle PowerShell GitHub Action #region Getting Started @" ### 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 `turtle`. "@ @" ### Drawing Squares <div align='center'> $( $null = Get-Turtle Square 10 | Set-Turtle -Property Stroke '#4488ff' | Save-Turtle -Path ./Examples/Square.svg ) <img src='./Examples/Square.svg' alt='Square' width='50%' /> </div> Let's start simple, by drawing a square with a series of commands. ~~~PowerShell $( $drawSquare1 = { 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" } $drawSquare1 ) ~~~ "@ @' We can also write this using a method chain: ~~~PowerShell $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: ~~~PowerShell $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. ~~~PowerShell 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: ~~~PowerShell 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: ~~~PowerShell 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: ~~~PowerShell $turtle = New-Turtle foreach ($n in 1..6) { $turtle = $turtle.Forward(10).Rotate(60) } $turtle | Save-Turtle "./Hexagon.svg" ~~~ '@ @" <div align='center'> $( $null = turtle ('Forward', 10, 'Rotate', 60 * 6) | Set-Turtle -Property Stroke '#4488ff' | Save-Turtle -Path ./Examples/Hexagon.svg ) <img src='./Examples/Hexagon.svg' alt='Hexagon' width='50%' /> </div> "@ @" Because this Turtle generates SVG, we can also use it to create patterns. "@ $MakeHexagonPattern = { turtle ('Forward', 10, 'Rotate', 60 * 6) | Set-Turtle -Property Stroke '#4488ff' | Save-Turtle -Path ./Examples/HexagonPattern.svg -Property Pattern } @" ~~~PowerShell $MakeHexagonPattern ~~~ "@ $HexPattern = . $MakeHexagonPattern @" <div align='center'> <img src='./Examples/$($HexPattern.Name)' alt='Hexagon Pattern' width='50%' /> </div> "@ #region LSystems $box1 = { Turtle BoxFractal 5 1 | Set-Turtle Stroke '#4488ff' | Save-Turtle ./Examples/BoxFractal1.svg } $box2 = { Turtle BoxFractal 5 2 | Set-Turtle Stroke '#4488ff' | Save-Turtle ./Examples/BoxFractal2.svg } $box3 = { Turtle BoxFractal 5 3 | Set-Turtle Stroke '#4488ff' | Save-Turtle ./Examples/BoxFractal3.svg } @" ### Drawing Fractals Turtle is often used to draw fractals. Many fractals can be described in something called a [L-System](https://en.wikipedia.org/wiki/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](https://en.wikipedia.org/wiki/Vicsek_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: ~~~PowerShell $box1 $box2 $box3 ~~~ $( $null = @( . $box1 . $box2 . $box3 ) ) <div align='center'> <img src='./Examples/BoxFractal1.svg' alt='Box Fractal 1' width='50%' /> <img src='./Examples/BoxFractal2.svg' alt='Box Fractal 2' width='50%' /> <img src='./Examples/BoxFractal3.svg' alt='Box Fractal 3' width='50%' /> </div> "@ @" This implementation of Turtle has quite a few built-in fractals. For example, here is an example of a pattern comprised of Koch Snowflakes: "@ $MakeSnowflakePattern = { 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 } @" ~~~PowerShell $MakeSnowflakePattern ~~~ "@ $SnowFlakePattern = . $MakeSnowflakePattern @" <div align='center'> <img src='./Examples/$($SnowFlakePattern.Name)' alt='Snowflake Pattern' width='50%' /> </div> "@ @" We can also animate the pattern, for endless variety: ~~~PowerShell $( @(Get-Content ./Examples/EndlessSnowflake.turtle.ps1 | Select-Object -Skip 1) -join [Environment]::NewLine ) ~~~ "@ @" <div align='center'> <img src='./Examples/EndlessSnowflake.svg' alt='Endless Snowflake Pattern' width='100%' /> </div> "@ #endregion LSystems #region Turtles in HTML @" ### 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? ~~~PowerShell 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 "@ #endregion Turtles in HTML #region Turtles in PNG @" ### 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`. ~~~PowerShell turtle SierpinskiTriangle | Set-Turtle Stroke '#4488ff' | Save-Turtle ./SierpinskiTriangle.png ~~~ "@ #endregion Turtles in PNG #region Call To Action @" ### 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! "@ #endregion Call To Action # "" "" |