### Install Chiplotle using pipx

Source: https://github.com/cyprienh/chiplotle3/blob/main/INSTALL.md

Recommended method for installing the official Chiplotle release if you only need the `chiplotle3` command. Ensure pipx is installed and configured.

```bash
pipx install chiplotle3
```

--------------------------------

### Example Serial Port Listing Before Adapter

Source: https://github.com/cyprienh/chiplotle3/blob/main/src/chiplotle3/documentation/chapters/hardware/index.md

This is an example output of listing serial ports before plugging in a USB to Serial adapter on a macOS system.

```bash
douglas$ ls /dev/tty.*
/dev/tty.Bluetooth-Modem        /dev/tty.Bluetooth-PDA-Sync
```

--------------------------------

### Install Chiplotle with pip

Source: https://context7.com/cyprienh/chiplotle3/llms.txt

Use pip to install Chiplotle globally or within a virtual environment.

```bash
pip install chiplotle3
```

--------------------------------

### Instantiate Plotters

Source: https://github.com/cyprienh/chiplotle3/blob/main/src/chiplotle3/documentation/chapters/tutorial/intro.md

Initialize the Chiplotle setup routine and import plotter definitions. This prepares Chiplotle to interact with available plotters.

```python
plts = instantiate_plotters( )
```

--------------------------------

### Example Serial Port Listing After Adapter

Source: https://github.com/cyprienh/chiplotle3/blob/main/src/chiplotle3/documentation/chapters/hardware/index.md

This is an example output of listing serial ports after plugging in a USB to Serial adapter on a macOS system. The new entries indicate the detected serial ports.

```bash
douglas$ ls /dev/tty.*
/dev/tty.Bluetooth-Modem        /dev/tty.KeySerial1
/dev/tty.Bluetooth-PDA-Sync     /dev/tty.USA19Hfa14P1.1
```

--------------------------------

### Start Chiplotle from Command Line

Source: https://github.com/cyprienh/chiplotle3/blob/main/src/chiplotle3/documentation/chapters/tutorial/intro.md

Execute this command in the terminal to launch Chiplotle in interactive mode. Ensure the chiplotle/scripts directory is in your PATH.

```bash
$ chiplotle
```

--------------------------------

### Get Help on SP Command

Source: https://github.com/cyprienh/chiplotle3/blob/main/src/chiplotle3/documentation/chapters/tutorial/intro.md

Use the Python help() function within the Chiplotle interactive mode to get detailed information about any command, including its required parameters.

```python
chiplotle> help(SP)
```

--------------------------------

### Launch Virtual Plotter Shell

Source: https://context7.com/cyprienh/chiplotle3/llms.txt

Starts an interactive Python shell with a virtual plotter for testing without hardware. A virtual plotter is pre-instantiated for immediate use.

```bash
# Start virtual plotter shell
chiplotle3_virtual
```

```python
# Inside the shell, a virtual plotter is pre-instantiated
# >>> plotter.write(shapes.rectangle(2000, 1000))
# >>> io.view(plotter)
```

--------------------------------

### Draw a Square with Chiplotle

Source: https://github.com/cyprienh/chiplotle3/blob/main/src/chiplotle3/documentation/chapters/tutorial/intro.md

A basic example demonstrating Chiplotle commands to draw a square. It includes selecting a pen, moving the pen, and drawing lines.

```python
plotter.select_pen(1)
plotter.write(PU([(100,100)]))
plotter.write(PD([(200,100), (200,200), (100,200), (100,100)]))
plotter.select_pen(0)
```

--------------------------------

### Launch Interactive Chiplotle Shell

Source: https://context7.com/cyprienh/chiplotle3/llms.txt

Starts an interactive Python shell with Chiplotle pre-loaded and plotters auto-detected. Use this to interactively control plotters and write shapes.

```bash
# Start interactive chiplotle shell
chiplotle3
```

```python
# Inside the shell:
# >>> plotter = instantiate_plotters()[0]
# >>> plotter.select_pen(1)
# >>> plotter.write(shapes.circle(1000))
```

--------------------------------

### Get Help on a Shape Function

Source: https://github.com/cyprienh/chiplotle3/blob/main/src/chiplotle3/documentation/chapters/tutorial/shapes.md

Retrieves detailed information about a specific shape constructor, such as `shapes.circle`. The shapes module must be loaded.

```python
help(shapes.circle)
```

--------------------------------

### Sample HPGL Commands

Source: https://github.com/cyprienh/chiplotle3/blob/main/src/chiplotle3/documentation/chapters/tutorial/intro.md

An example of raw HPGL commands typically found in a text file. These commands control plotter functions like pen selection and movement.

```hpgl
SP1;
PU100,100;
PD200,100;
PD200,200;
PD100,100;
PD100,100;
SP0;
```

--------------------------------

### Format HPGL Commands in Chiplotle

Source: https://github.com/cyprienh/chiplotle3/blob/main/src/chiplotle3/documentation/chapters/fundamentals/index.md

Shows how to access the `format` attribute of Chiplotle HPGL commands to get their string representation as sent to the plotter.

```default
chiplotle> t = PD( )
chiplotle> t.format
'PD;'
```

--------------------------------

### Get a Specific Plotter

Source: https://github.com/cyprienh/chiplotle3/blob/main/src/chiplotle3/documentation/chapters/tutorial/intro.md

If you have only one plotter or need to access a specific one, retrieve it from the list returned by `instantiate_plotters()`.

```python
plotter = instantiate_plotters( )[0]
```

--------------------------------

### Instantiate HPGL Commands in Chiplotle

Source: https://github.com/cyprienh/chiplotle3/blob/main/src/chiplotle3/documentation/chapters/fundamentals/index.md

Demonstrates how to instantiate HPGL commands like PD and CI. Some commands require arguments, while others do not.

```default
chiplotle> PD( )
PD(xy=[])
```

```default
chiplotle> CI(10)
CI(chordangle=None, radius=10.0)
```

--------------------------------

### Instantiate Virtual Plotter

Source: https://context7.com/cyprienh/chiplotle3/llms.txt

Create a virtual plotter for testing and previewing artwork without physical hardware. Supports default or custom paper dimensions.

```python
from chiplotle3 import instantiate_virtual_plotter
from chiplotle3 import shapes, Group
from chiplotle3.tools import io

# Create a virtual plotter with default 8.5x11" paper
plotter = instantiate_virtual_plotter()

# Or specify custom dimensions (in plotter units)
from chiplotle3.geometry.core.coordinate import Coordinate
plotter = instantiate_virtual_plotter(
    left_bottom=Coordinate(0, 0),
    right_top=Coordinate(16000, 10000)
)

# Draw shapes on the virtual plotter
plotter.select_pen(1)
plotter.goto(5000, 5000)
c = shapes.circle(1000)
plotter.write(c)

# Preview the virtual plotter output
io.view(plotter)
```

--------------------------------

### Import Chiplotle Library

Source: https://github.com/cyprienh/chiplotle3/blob/main/src/chiplotle3/documentation/chapters/tutorial/intro.md

Begin your Python script by importing the Chiplotle library to access its functionalities.

```python
from chiplotle import *
```

--------------------------------

### Run a Python Script

Source: https://github.com/cyprienh/chiplotle3/blob/main/src/chiplotle3/documentation/chapters/tutorial/intro.md

Execute a Chiplotle Python script from the command line using the standard Python interpreter.

```bash
$ python square.py
```

--------------------------------

### Import HPGL File Commands

Source: https://context7.com/cyprienh/chiplotle3/llms.txt

Shows how to import an HPGL file into Chiplotle3 objects, optionally filtering specific commands during import. Use this to parse existing HPGL files.

```python
from chiplotle3.tools.io import import_hpgl_file
from chiplotle3.tools import io

# Import an HPGL file
commands = import_hpgl_file("drawing.hpgl")

# View the imported commands
print(commands)
# Output: [SP(pen=1), PU(xy=[100. 100.]), PD(xy=[200. 100.]), ...]

# Filter specific commands during import
pen_commands = import_hpgl_file("drawing.hpgl", filter_commands=['SP', 'PU', 'PD'])

# Preview the imported file
io.view(commands)
```

--------------------------------

### Draw a Square using PU and PD Commands

Source: https://github.com/cyprienh/chiplotle3/blob/main/src/chiplotle3/documentation/chapters/tutorial/intro.md

This sequence demonstrates drawing a square by lifting the pen (PU), moving down (PD) to draw lines, and finally lifting the pen again. Coordinates are provided as a list of tuples.

```python
chiplotle> plotter.select_pen(1)
chiplotle> plotter.write(PU([(100,100)]))
chiplotle> plotter.write(PD([(200,100), (200,200), (100,200), (100,100)]))
chiplotle> plotter.write(PU([]))
```

--------------------------------

### Simulate Live Plotting with a Virtual Plotter

Source: https://github.com/cyprienh/chiplotle3/blob/main/src/chiplotle3/documentation/chapters/plotters/index.md

Use a virtual plotter to simulate live plotting, including pen selection, movement, and querying plotter state. Requires instantiation of a virtual plotter object.

```python
from chiplotle import *
from chiplotle3.tools.plottertools import instantiate_virtual_plotter
plotter =  instantiate_virtual_plotter(type="HP7550A")
plotter.margins.hard.draw_outline()
plotter.select_pen(2)
plotter.goto(0,0)
plotter.pen_down()
plotter.goto(1000,1000)
plotter.pen_up()
plotter.select_pen(0)
io.view(plotter)
```

--------------------------------

### Preview Shapes with io.view

Source: https://context7.com/cyprienh/chiplotle3/llms.txt

Displays Chiplotle shapes for previewing without a physical plotter. Exports to EPS format by default and opens in system viewer. Supports PNG and SVG formats.

```python
from chiplotle3 import shapes, Group
from chiplotle3.tools import io
from chiplotle3.geometry.transforms import rotate, offset
import math

# Create artwork
artwork = Group()
for i in range(12):
    star = shapes.star_outline(1000, 1000, 6)
    rotate(star, (math.pi / 6) * i)
    artwork.append(star)

# View as EPS (default)
io.view(artwork)

# View as PNG
io.view(artwork, fmt='png')

# View as SVG
io.view(artwork, fmt='svg')
```

--------------------------------

### Create and Save Shapes to HPGL

Source: https://context7.com/cyprienh/chiplotle3/llms.txt

Demonstrates creating basic shapes like circles and rectangles, grouping them, and saving the artwork to an HPGL file. Also shows saving a list of shapes.

```python
circle = shapes.circle(1000)
rect = shapes.rectangle(2000, 1000)
offset(rect, (3000, 0))

# Group them together
artwork = Group([circle, rect])

# Save to HPGL file
save_hpgl(artwork, "my_drawing.hpgl")

# Can also save a list of shapes
shapes_list = [shapes.circle(500), shapes.star_outline(800, 800, 6)]
save_hpgl(shapes_list, "shapes.plt")
```

--------------------------------

### import_hpgl_file - Load HPGL File

Source: https://context7.com/cyprienh/chiplotle3/llms.txt

Reads a text HPGL file and converts it to Chiplotle-HPGL class instances.

```APIDOC
## import_hpgl_file - Load HPGL File

### Description
Reads a text HPGL file and converts it to Chiplotle-HPGL class instances.

### Method
`import_hpgl_file`

### Parameters
#### Path Parameters
- **file_path** (string) - Required - Path to the HPGL file.
- **filter_commands** (list of strings) - Optional - A list of HPGL command mnemonics to filter by.

### Request Example
```python
from chiplotle3.tools.io import import_hpgl_file
from chiplotle3.tools import io

# Import an HPGL file
commands = import_hpgl_file("drawing.hpgl")

# View the imported commands
print(commands)

# Filter specific commands during import
pen_commands = import_hpgl_file("drawing.hpgl", filter_commands=['SP', 'PU', 'PD'])

# Preview the imported file
io.view(commands)
```

### Response
#### Success Response (200)
- **commands** (list) - A list of Chiplotle-HPGL class instances representing the HPGL commands.

#### Response Example
```
[SP(pen=1), PU(xy=[100. 100.]), PD(xy=[200. 100.]), ...]
```
```

--------------------------------

### Instantiate Physical Plotters

Source: https://context7.com/cyprienh/chiplotle3/llms.txt

Automatically detect and connect to all available physical pen plotters via serial ports. Use the first detected plotter for drawing operations.

```python
from chiplotle3 import instantiate_plotters

# Auto-detect and connect to all available plotters
plotters = instantiate_plotters()

# Use the first plotter found
plotter = plotters[0]

# Check plotter information
print(f"Plotter type: {plotter.type}")
print(f"Drawing area: {plotter.margins.soft.width} x {plotter.margins.soft.height}")

# Select a pen and draw a circle
plotter.select_pen(1)
plotter.goto(5000, 5000)
plotter.write(hpgl.CI(1000))  # Circle with radius 1000

# Return pen to carousel
plotter.select_pen(0)
```

--------------------------------

### List Available Shape Constructors

Source: https://github.com/cyprienh/chiplotle3/blob/main/src/chiplotle3/documentation/chapters/tutorial/shapes.md

Displays all available shape constructors within the shapes module. Ensure the shapes module is loaded.

```python
dir(shapes)
```

--------------------------------

### Create a Circle Shape

Source: https://github.com/cyprienh/chiplotle3/blob/main/src/chiplotle3/documentation/chapters/tutorial/shapes.md

Instantiates a circle with a specified radius. The shapes module must be loaded.

```python
c = shapes.circle(1000)
```

--------------------------------

### view - Preview Shapes

Source: https://context7.com/cyprienh/chiplotle3/llms.txt

Displays Chiplotle shapes for previewing without a physical plotter. Exports to EPS format by default and opens in system viewer.

```APIDOC
## view - Preview Shapes

### Description
Displays Chiplotle shapes for previewing without a physical plotter. Exports to EPS format by default and opens in system viewer.

### Method
`io.view`

### Parameters
#### Path Parameters
- **shapes** (object or list) - Required - The Chiplotle shape(s) or Group object to preview.
- **fmt** (string) - Optional - The output format. Supported formats include 'eps' (default), 'png', 'svg'.

### Request Example
```python
from chiplotle3 import shapes, Group
from chiplotle3.tools import io
from chiplotle3.geometry.transforms import rotate, offset
import math

# Create artwork
artwork = Group()
for i in range(12):
    star = shapes.star_outline(1000, 1000, 6)
    rotate(star, (math.pi / 6) * i)
    artwork.append(star)

# View as EPS (default)
io.view(artwork)

# View as PNG
io.view(artwork, fmt='png')

# View as SVG
io.view(artwork, fmt='svg')
```
```

--------------------------------

### Display PATH Environment Variable

Source: https://github.com/cyprienh/chiplotle3/blob/main/src/chiplotle3/documentation/chapters/faq/index.md

Displays the current value of the PATH environment variable in Windows. This command helps in verifying path settings.

```batch
echo %PATH%
```

--------------------------------

### Create an Arrow from a Bezier Path

Source: https://github.com/cyprienh/chiplotle3/blob/main/src/chiplotle3/documentation/chapters/tutorial/shapes.md

Constructs an arrow shape based on a Bezier path. Requires the 'shapes' module and potentially an 'arrow' constructor.

```python
coords = [(0, 0), (0, 1000), (1000, 1000)]
p = shapes.bezier_path(coords, 1)
a = arrow(p, 100, 200)
```

--------------------------------

### Create a Rectangle Shape

Source: https://github.com/cyprienh/chiplotle3/blob/main/src/chiplotle3/documentation/chapters/tutorial/shapes.md

Instantiates a rectangle with specified width and height. The shapes module must be loaded.

```python
r = shapes.rectangle(500, 1000)
```

--------------------------------

### List Serial Ports on OSX/Linux

Source: https://github.com/cyprienh/chiplotle3/blob/main/src/chiplotle3/documentation/chapters/hardware/index.md

Use this command to list available serial ports in the /dev directory on macOS and Linux. Plug in your USB to Serial adapter and run the command again to identify the new device name.

```bash
ls /dev/tty.*
```

--------------------------------

### Create Star Shape Outline

Source: https://context7.com/cyprienh/chiplotle3/llms.txt

Constructs a star shape using `shapes.star_outline`. Specify `width`, `height`, and `num_points`. A loop can create multiple stars with different dimensions.

```python
star = shapes.star_outline(width=2000, height=2000, num_points=5)

stars = Group()
for i in range(5, 12):
    s = shapes.star_outline(width=500 * i, height=500 * i, num_points=i)
    stars.append(s)

io.view(stars)
```

--------------------------------

### goto - Move Pen to Position

Source: https://context7.com/cyprienh/chiplotle3/llms.txt

Convenience method to move the pen to absolute coordinates without drawing.

```APIDOC
## goto - Move Pen to Position

### Description
Convenience method to move the pen to absolute coordinates without drawing.

### Method
`plotter.goto`

### Parameters
#### Path Parameters
- **position** (tuple, Coordinate object, or x, y arguments) - Required - The target coordinates to move the pen to.

### Request Example
```python
from chiplotle3 import instantiate_plotters, hpgl
from chiplotle3.geometry.core.coordinate import Coordinate

plotter = instantiate_plotters()[0]

# Move to coordinates using x, y arguments
plotter.goto(5000, 5000)

# Move using a tuple
plotter.goto((3000, 2000))

# Move using a Coordinate object
plotter.goto(Coordinate(1000, 1000))

# Built-in position shortcuts
plotter.goto_center()
plotter.goto_origin()
plotter.goto_bottom_left()
plotter.goto_top_right()

# Draw after moving
plotter.select_pen(1)
plotter.goto(2000, 2000)
plotter.pen_down()
plotter.goto(4000, 4000)
plotter.pen_up()
```
```

--------------------------------

### Select Pen using SP Command

Source: https://github.com/cyprienh/chiplotle3/blob/main/src/chiplotle3/documentation/chapters/tutorial/intro.md

Use the SP command to select a pen for plotting. Parameters are enclosed in parentheses. Refer to the API for command details.

```python
chiplotle> SP(1)
```

--------------------------------

### Access Shape Properties

Source: https://github.com/cyprienh/chiplotle3/blob/main/src/chiplotle3/documentation/chapters/tutorial/shapes.md

Demonstrates accessing properties like 'center' and 'width' of a shape object. Requires a shape to be instantiated first.

```python
>>> c = shapes.circle(1000)
>>> c.center
Coordinate([0.0, 0.0])
>>> c.width
2000.0
```

--------------------------------

### Create and Manipulate Groups of Shapes

Source: https://context7.com/cyprienh/chiplotle3/llms.txt

Demonstrates creating a group from a list of shapes, nesting groups, and accessing individual shapes within a group.

```python
shapes_list = [
    shapes.circle(300),
    shapes.ellipse(600, 200),
    shapes.rectangle(400, 400)
]
another_group = Group(shapes_list)

# Nested groups
main_group = Group()
main_group.append(group)
main_group.append(another_group)

# Access individual shapes
first_shape = group[0]
num_shapes = len(group)

io.view(main_group)
```

--------------------------------

### Plot HPGL File to Plotter

Source: https://context7.com/cyprienh/chiplotle3/llms.txt

A command-line utility to send an HPGL file directly to a connected plotter. Ensure the plotter is connected and recognized before execution.

```bash
# Plot an HPGL file
plot_hpgl_file artwork.hpgl
```

--------------------------------

### Create Bezier Curve Paths

Source: https://context7.com/cyprienh/chiplotle3/llms.txt

Generates Bezier curve paths using `shapes.bezier_path` with varying `curvature` and `interpolation_count`. The `points` parameter defines the control points.

```python
points = [(0, 0), (1000, 2000), (2000, 0), (3000, 2000), (4000, 0)]
paths = Group()

p1 = shapes.bezier_path(points, curvature=0)
paths.append(p1)

p2 = shapes.bezier_path(points, curvature=0.5)
paths.append(p2)

p3 = shapes.bezier_path(points, curvature=1)
paths.append(p3)

smooth_path = shapes.bezier_path(points, curvature=0.8, interpolation_count=100)
paths.append(smooth_path)

io.view(paths)
```

--------------------------------

### Basic HPGL Pen and Movement Commands

Source: https://context7.com/cyprienh/chiplotle3/llms.txt

Utilizes low-level HPGL commands for direct plotter control, including pen up/down, absolute and relative movement, and pen selection. Ensure a plotter is instantiated before use.

```python
from chiplotle3 import hpgl
from chiplotle3 import instantiate_plotters

plotter = instantiate_plotters()[0]

# Pen Up - raise pen from paper
plotter.write(hpgl.PU())

# Pen Down - lower pen to paper
plotter.write(hpgl.PD())

# Plot Absolute - move to absolute coordinates
plotter.write(hpgl.PA([(1000, 1000), (2000, 2000)]))

# Plot Relative - move relative to current position
plotter.write(hpgl.PR([(500, 0), (0, 500)]))

# Select Pen - choose pen from carousel (0 = put pen away)
plotter.write(hpgl.SP(1))  # Select pen 1
plotter.write(hpgl.SP(0))  # Put pen away

# Draw a simple square using raw HPGL
plotter.write(hpgl.SP(1))
plotter.write(hpgl.PU([(0, 0)]))
plotter.write(hpgl.PD([(1000, 0), (1000, 1000), (0, 1000), (0, 0)]))
plotter.write(hpgl.PU())
plotter.write(hpgl.SP(0))
```

--------------------------------

### Plot HPGL File from Chiplotle

Source: https://github.com/cyprienh/chiplotle3/blob/main/src/chiplotle3/documentation/chapters/tutorial/intro.md

Use the `write_file()` method within a Chiplotle session to send HPGL commands from a specified file to the plotter.

```python
plotter.write_file('my_file.hpgl')
```

--------------------------------

### Write Informative Docstrings

Source: https://github.com/cyprienh/chiplotle3/blob/main/src/chiplotle3/documentation/chapters/contributors/index.md

Always include an informative docstring when defining a new function or class. This aids in understanding the purpose and usage of code elements.

```default
def foo(x, y):
   '''This is an informative docstring.'''
```

--------------------------------

### HPGL Labels and Text Formatting

Source: https://context7.com/cyprienh/chiplotle3/llms.txt

Demonstrates adding text labels to the plotter using HPGL commands. Includes setting character size, direction, slant, and origin positioning.

```python
from chiplotle3 import hpgl
from chiplotle3 import instantiate_plotters

plotter = instantiate_plotters()[0]
plotter.select_pen(1)

# Label - draw text at current position
plotter.goto(1000, 1000)
plotter.write(hpgl.LB("Hello Plotter!"))

# Set character size (width, height in cm)
plotter.write(hpgl.SI(width=0.3, height=0.4))
plotter.goto(1000, 2000)
plotter.write(hpgl.LB("Larger Text"))

# Set relative character size (percentage of P1-P2 distance)
plotter.write(hpgl.SR(width=2, height=3))

# Set label direction (run=cos(angle), rise=sin(angle))
plotter.write(hpgl.DI(run=0.707, rise=0.707))  # 45 degrees
plotter.goto(3000, 1000)
plotter.write(hpgl.LB("Angled Text"))

# Character slant (italic effect) - tan of angle
plotter.write(hpgl.SL(tan=0.3))
plotter.goto(3000, 2000)
plotter.write(hpgl.LB("Slanted"))

# Label origin positioning (1-9 or 11-19)
plotter.write(hpgl.LO(origin=5))  # Center-justified
plotter.goto(5000, 3000)
plotter.write(hpgl.LB("Centered"))
```

--------------------------------

### Move Pen to Position with plotter.goto

Source: https://context7.com/cyprienh/chiplotle3/llms.txt

Convenience method to move the pen to absolute coordinates without drawing. Supports x, y arguments, tuples, Coordinate objects, and built-in position shortcuts.

```python
from chiplotle3 import instantiate_plotters, hpgl

plotter = instantiate_plotters()[0]

# Move to coordinates using x, y arguments
plotter.goto(5000, 5000)

# Move using a tuple
plotter.goto((3000, 2000))

# Move using a Coordinate object
from chiplotle3.geometry.core.coordinate import Coordinate
plotter.goto(Coordinate(1000, 1000))

# Built-in position shortcuts
plotter.goto_center()
plotter.goto_origin()
plotter.goto_bottom_left()
plotter.goto_top_right()

# Draw after moving
plotter.select_pen(1)
plotter.goto(2000, 2000)
plotter.pen_down()
plotter.goto(4000, 4000)
plotter.pen_up()
```

--------------------------------

### Write HPGL File using Chiplotle

Source: https://github.com/cyprienh/chiplotle3/blob/main/src/chiplotle3/documentation/chapters/faq/index.md

Within a Chiplotle session, use the `write_file` method to send an HPGL file to the plotter. This method handles buffer management.

```python
chiplotle> plotter.write_file('my_file.hpgl')
```

--------------------------------

### Preview HPGL File

Source: https://context7.com/cyprienh/chiplotle3/llms.txt

Preview an HPGL file without sending it to a physical plotter. This is useful for verifying the contents of an HPGL file before plotting.

```bash
# View HPGL file
view_hpgl_file drawing.hpgl
```

--------------------------------

### Collect Plotter Commands to a Group

Source: https://github.com/cyprienh/chiplotle3/blob/main/src/chiplotle3/documentation/chapters/plotters/index.md

Collect plotter commands into a list and then view them using io.view(). This is useful for algorithmic command generation when direct plotter interaction is not needed.

```python
from chiplotle import *
commands = []
commands.append(SP(1))
commands.append(PA([(0,0)]))
commands.append(PD())
commands.append(PA([(1000,1000)]))
commands.append(PU())
commands.append(SP(0))
io.view(commands)
```

--------------------------------

### Use Double Pound Signs for Comments

Source: https://github.com/cyprienh/chiplotle3/blob/main/src/chiplotle3/documentation/chapters/contributors/index.md

Introduce comments using two pound signs followed by a single space. This distinguishes comments from code elements.

```default
## comment before foo
def foo(x, y):
   return x + y
```

--------------------------------

### Send HPGL File to Plotter with plotter.write_file

Source: https://context7.com/cyprienh/chiplotle3/llms.txt

Sends the contents of an HPGL file directly to the plotter. Use this to send pre-existing HPGL files for plotting.

```python
from chiplotle3 import instantiate_plotters

plotter = instantiate_plotters()[0]

# Send an HPGL file to the plotter
plotter.write_file("artwork.hpgl")
plotter.write_file("design.plt")
```

--------------------------------

### Organize Class Definitions

Source: https://github.com/cyprienh/chiplotle3/blob/main/src/chiplotle3/documentation/chapters/contributors/index.md

Structure class definitions into specific sections: initialization, overloads, private attributes, public attributes, private methods, and public methods. This promotes a clear and organized class structure.

```default
class FooBar(object):

   def __init__(self, x, y):
      ...

   ## OVERLOADS ##

   def __repr__(self):
      ...

   def __str__(self):
      ...

   ## PRIVATE ATTRIBUTES ##

   @property
   def _foo(self):
      ...

   ## PUBLIC ATTRIBUTES ##

   @property
   def bar(self):
      ...

   ## PRIVATE METHODS ##

   def _blah(self, x, y):
      ...

   ## PUBLIC METHODS ##

   def baz(self, z):
      ...
```

--------------------------------

### Execute HPGL File Sender Script

Source: https://github.com/cyprienh/chiplotle3/blob/main/src/chiplotle3/documentation/chapters/faq/index.md

Use the `plot_hpgl_file.py` script to send an HPGL file to the plotter from the command line. Provide the filename as an argument.

```bash
$ plot_hpgl_file.py my_file.hpgl
```

--------------------------------

### Send HPGL File via Serial Port

Source: https://github.com/cyprienh/chiplotle3/blob/main/src/chiplotle3/documentation/chapters/faq/index.md

This command sequence sends an HPGL file to a serial port. Ensure the serial port is configured correctly before execution.

```bash
$ stty /dev/ttyUSB0 9600
$ cat bird.hpgl > /dev/ttyUSB0
```

--------------------------------

### Move Pen using Plotter Methods

Source: https://github.com/cyprienh/chiplotle3/blob/main/src/chiplotle3/documentation/chapters/tutorial/intro.md

Utilize plotter.pen_up() and plotter.pen_down() as convenient shortcuts for the PU and PD HPGL commands, respectively. They accept a list of coordinate tuples.

```python
chiplotle> plotter.pen_up([(100,100)])
chiplotle> plotter.pen_down([(100,100)])
```

--------------------------------

### Write HPGL Commands using Chiplotle

Source: https://github.com/cyprienh/chiplotle3/blob/main/src/chiplotle3/documentation/chapters/faq/index.md

Send HPGL commands directly to the plotter from within a Chiplotle session using the `write` method. Ensure `PA()` is a valid HPGL command.

```python
chiplotle> plotter.write(PA( ))
```

--------------------------------

### Import One Module Per Line

Source: https://github.com/cyprienh/chiplotle3/blob/main/src/chiplotle3/documentation/chapters/contributors/index.md

Import modules individually on separate lines. This improves readability and maintainability of import statements.

```default
from foo import x
from foo import y
from foo import z
```

--------------------------------

### HPGL Line Types and Fill Patterns

Source: https://context7.com/cyprienh/chiplotle3/llms.txt

Configures line styles (dotted, dashed) and fill patterns (hatching, cross-hatching) for shapes using HPGL commands. Resets to solid lines by default.

```python
from chiplotle3 import hpgl
from chiplotle3 import instantiate_plotters

plotter = instantiate_plotters()[0]
plotter.select_pen(1)

# Line Type patterns:
# 0 = point at each coordinate
# 1 = dotted (....)
# 2 = short dashes (--)
# 3 = long dashes (---)
# 4 = dash-dot (-.-)
# 5 = long dash-dot (---.)
# 6 = long dash-dot-dot (---..)

# Set dashed line type
plotter.write(hpgl.LT(pattern=2, length=4))
plotter.goto(0, 0)
plotter.write(hpgl.EA(xy=(2000, 1000)))

# Reset to solid line
plotter.write(hpgl.LT())  # No parameters = solid

# Fill Type patterns:
# 1-2 = Solid fill
# 3 = Hatching (parallel lines)
# 4 = Cross-hatching

# Set fill type with spacing and angle
plotter.write(hpgl.FT(type=3, space=50, angle=45))  # 45-degree hatching
plotter.goto(3000, 0)
plotter.write(hpgl.RR(xy=(2000, 1000)))  # Filled rectangle

# Cross-hatching
plotter.write(hpgl.FT(type=4, space=30, angle=0))
plotter.goto(6000, 0)
plotter.write(hpgl.RR(xy=(2000, 1000)))
```

--------------------------------

### Draw a Random Zigzag with Chiplotle

Source: https://github.com/cyprienh/chiplotle3/blob/main/src/chiplotle3/documentation/chapters/tutorial/intro.md

This script draws a random zigzag pattern. It imports necessary libraries, sets up the plotter, generates random coordinates, and draws the path.

```python
from chiplotle import *
import random

plotter = instantiate_plotters( )[0]

plotter.select_pen(1)

coords = [(x, random.randint(0, 1000)) for x in range(0, 1000, 10)]
plotter.write(PD(coords))

plotter.select_pen(0)
```

--------------------------------

### Precede Private Attributes and Methods with Underscore

Source: https://github.com/cyprienh/chiplotle3/blob/main/src/chiplotle3/documentation/chapters/contributors/index.md

Prefix private class attributes and methods with a single underscore. This indicates that these members are intended for internal use only.

```default
class FooBar(object):

   ## PRIVATE ATTRIBUTES ##

   @property
   def _foo(self):
      ...

   ## PRIVATE METHODS ##

   def _blah(self, x, y):
      ...
```

--------------------------------

### Select Pen using Plotter Method

Source: https://github.com/cyprienh/chiplotle3/blob/main/src/chiplotle3/documentation/chapters/tutorial/intro.md

Directly use the plotter's select_pen method as a shortcut for the SP HPGL command. This method is equivalent to plotter.write(SP()).

```python
chiplotle> plotter.select_pen(1)
```

--------------------------------

### Add Blank Lines After Imports

Source: https://github.com/cyprienh/chiplotle3/blob/main/src/chiplotle3/documentation/chapters/contributors/index.md

Include two blank lines after import statements before the rest of the module code. This visually separates imports from definitions.

```default
from foo import x
from foo import y
from foo import z


class Foo(object):
   ... 
   ...
```

--------------------------------

### Indent with 3 Spaces

Source: https://github.com/cyprienh/chiplotle3/blob/main/src/chiplotle3/documentation/chapters/contributors/index.md

Use three spaces for indentation, not tabs. This ensures consistent code formatting across the project.

```default
def foo(x, y):
   return x + y
```

--------------------------------

### Write HPGL Command via Plotter

Source: https://github.com/cyprienh/chiplotle3/blob/main/src/chiplotle3/documentation/chapters/tutorial/intro.md

Send an HPGL command, like SP(1), to the plotter using the plotter.write() method. This is the standard way to execute commands.

```python
chiplotle> plotter.write(SP(1))
```

--------------------------------

### Send Data to Plotter with plotter.write

Source: https://context7.com/cyprienh/chiplotle3/llms.txt

Primary method for sending HPGL commands, shapes, or strings to the plotter. Can send individual commands, shapes, groups, lists of commands, or raw HPGL strings.

```python
from chiplotle3 import instantiate_plotters, hpgl, shapes, Group

plotter = instantiate_plotters()[0]

# Write individual HPGL commands
plotter.write(hpgl.SP(1))
plotter.write(hpgl.CI(1000))

# Write a shape directly
circle = shapes.circle(500)
plotter.write(circle)

# Write a group of shapes
group = Group([
    shapes.circle(300),
    shapes.rectangle(600, 400)
])
plotter.write(group)

# Write a list of commands
commands = [
    hpgl.PU([(0, 0)]),
    hpgl.PD([(1000, 0), (1000, 1000)]),
    hpgl.PU()
]
plotter.write(commands)

# Write raw HPGL string
plotter.write("SP1;PA1000,1000;CI500;")
```

--------------------------------

### Create Archimedean Spirals

Source: https://context7.com/cyprienh/chiplotle3/llms.txt

Generates Fermat's and hyperbolic spirals using `shapes.spiral_archimedean`. Ensure `spirals` list is initialized before appending.

```python
s2 = shapes.spiral_archimedean(1500, wrapping_constant=2, direction="ccw")
offset(s2, (4000, 0))
spirals.append(s2)

s3 = shapes.spiral_archimedean(2500, wrapping_constant=-1, segments=800)
rotate(s3, math.pi * 1.5)
offset(s3, (8000, 0))
spirals.append(s3)

io.view(spirals)
```

--------------------------------

### Create Arrow Shape

Source: https://context7.com/cyprienh/chiplotle3/llms.txt

Generates an arrow shape using `shapes.arrow` by combining a path with an arrowhead. Parameters `headwidth`, `headheight`, and `filled` control the arrow's appearance.

```python
coords = [(0, 0), (0, 1000), (2000, 1000)]
path = shapes.bezier_path(coords, curvature=0.8)
arrow = shapes.arrow(path, headwidth=200, headheight=300)

coords2 = [(0, 0), (1500, 500), (3000, 0)]
path2 = shapes.bezier_path(coords2, curvature=0.5)
filled_arrow = shapes.arrow(path2, headwidth=150, headheight=250, filled=True)

io.view(Group([arrow, filled_arrow]))
```

--------------------------------

### HPGL Drawing Primitives

Source: https://context7.com/cyprienh/chiplotle3/llms.txt

Executes HPGL commands for drawing basic shapes like circles, arcs, and rectangles directly on the plotter. Requires pen selection and positioning.

```python
from chiplotle3 import hpgl
from chiplotle3 import instantiate_plotters

plotter = instantiate_plotters()[0]
plotter.select_pen(1)
plotter.goto(5000, 5000)

# Circle - draw circle at current position
plotter.write(hpgl.CI(radius=1000))

# Circle with chord angle for smoother curves
plotter.write(hpgl.CI(radius=500, chordangle=5))

# Arc Absolute - draw arc from current position
# Parameters: center (x,y), sweep angle, chord tolerance
plotter.goto(3000, 3000)
plotter.write(hpgl.AA(xy=(3000, 4000), angle=180))

# Arc Relative
plotter.write(hpgl.AR(xy=(0, 1000), angle=90))

# Edge Rectangle Absolute - draw rectangle outline
plotter.goto(1000, 1000)
plotter.write(hpgl.EA(xy=(2000, 2000)))

# Edge Rectangle Relative
plotter.write(hpgl.ER(xy=(1500, 800)))

# Filled Rectangle Absolute
plotter.write(hpgl.RA(xy=(3500, 3500)))

# Edge Wedge - pie slice outline
plotter.goto(5000, 5000)
plotter.write(hpgl.EW(radius=1000, startangle=0, sweepangle=90))

# Filled Wedge
plotter.write(hpgl.WG(radius=800, startangle=90, sweepangle=45))
```

--------------------------------

### Scale Shapes In-Place

Source: https://context7.com/cyprienh/chiplotle3/llms.txt

Scales a shape in-place around a pivot point using `scale`. Supports uniform scaling by a factor or non-uniform scaling with a tuple `(x, y)`. A `pivot` can be specified.

```python
rect = shapes.rectangle(1000, 500)

scaled = Group()
for i in range(1, 6):
    r = shapes.rectangle(1000, 500)
    scale(r, i)
    scaled.append(r)

rect2 = shapes.rectangle(500, 500)
scale(rect2, (3, 1))

rect3 = shapes.rectangle(1000, 1000)
scale(rect3, 2, pivot=(500, 500))

io.view(Group([scaled, rect2, rect3]))
```

--------------------------------

### Translate Shapes In-Place

Source: https://context7.com/cyprienh/chiplotle3/llms.txt

Moves a shape by specified x and y offset values using `offset`. Useful for positioning shapes or creating grids.

```python
c = shapes.circle(500)
offset(c, (2000, 3000))

grid = Group()
for x in range(5):
    for y in range(5):
        circle = shapes.circle(200)
        offset(circle, (x * 600, y * 600))
        grid.append(circle)

io.view(grid)
```

--------------------------------

### Create Arcs in a Group

Source: https://github.com/cyprienh/chiplotle3/blob/main/src/chiplotle3/documentation/chapters/tutorial/shapes.md

Generates a group of arc_circle shapes with varying radii. Requires the 'shapes' and 'math' modules. Use `io.view()` to display the resulting group.

```python
g = shapes.group()
for radius in range(100, 1000, 100):
   a = shapes.arc_circle(radius, 1.0, math.pi)
   gr.append(a)
```

--------------------------------

### Include Space in Empty Parentheses

Source: https://github.com/cyprienh/chiplotle3/blob/main/src/chiplotle3/documentation/chapters/contributors/index.md

Add a single space within empty parentheses for function definitions. This improves visual clarity.

```default
def foo( ):
   ...
   ...
```

--------------------------------

### Separate Binary Operators with Space

Source: https://github.com/cyprienh/chiplotle3/blob/main/src/chiplotle3/documentation/chapters/contributors/index.md

Ensure binary operators are surrounded by a single space. This enhances code readability and prevents misinterpretation of operations.

```default
(a // b) + c == d
```

--------------------------------

### Create Archimedean Spiral

Source: https://context7.com/cyprienh/chiplotle3/llms.txt

Generate an Archimedean spiral with configurable radius and number of turns. Different wrapping constants create various spiral types (e.g., Fermat's, hyperbolic).

```python
from chiplotle3 import shapes, Group
from chiplotle3.geometry.transforms import offset, rotate
from chiplotle3.tools import io
import math

# Basic Archimedean spiral
spiral = shapes.spiral_archimedean(radius=2000, num_turns=5)

# Create different spiral types
spirals = Group()

# Archimedes' spiral (wrapping_constant=1)
s1 = shapes.spiral_archimedean(1500, wrapping_constant=1)
spirals.append(s1)
```

--------------------------------

### Create Circle Shape

Source: https://context7.com/cyprienh/chiplotle3/llms.txt

Generate a circle polygon with specified radius and number of segments. Can create multiple concentric circles using a Group.

```python
from chiplotle3 import shapes, Group
from chiplotle3.tools import io

# Create a simple circle with radius 1000 plotter units
c = shapes.circle(radius=1000)

# Create a smoother circle with more segments
smooth_circle = shapes.circle(radius=2000, segments=72)

# Create multiple concentric circles
circles = Group()
for r in range(500, 3000, 500):
    circles.append(shapes.circle(r))

io.view(circles)
```

--------------------------------

### Create Rectangle Shape

Source: https://context7.com/cyprienh/chiplotle3/llms.txt

Generate a rectangle polygon centered at the origin. Supports creating multiple rotated rectangles within a Group.

```python
from chiplotle3 import shapes, Group
from chiplotle3.geometry.transforms import offset, rotate
from chiplotle3.tools import io
import math

# Create a simple rectangle
rect = shapes.rectangle(width=2000, height=1000)

# Create multiple rotated rectangles
rectangles = Group()
for i in range(6):
    r = shapes.rectangle(3000, 500)
    rotate(r, math.pi / 6 * i)
    rectangles.append(r)

io.view(rectangles)
```

--------------------------------

### Save Shapes to HPGL File

Source: https://context7.com/cyprienh/chiplotle3/llms.txt

Saves Chiplotle shapes or HPGL commands to a text HPGL file. This is useful for later use or transfer to other systems.

```python
from chiplotle3 import shapes, Group
from chiplotle3.tools.io import save_hpgl
from chiplotle3.geometry.transforms import offset
```

--------------------------------

### Return Pen to Resting Position

Source: https://github.com/cyprienh/chiplotle3/blob/main/src/chiplotle3/documentation/chapters/tutorial/intro.md

Select pen zero using plotter.select_pen(0) to return the pen to its resting position, typically off the plotting surface.

```python
chiplotle> plotter.select_pen(0)
```

--------------------------------

### write_file - Send HPGL File to Plotter

Source: https://context7.com/cyprienh/chiplotle3/llms.txt

Sends the contents of an HPGL file directly to the plotter.

```APIDOC
## write_file - Send HPGL File to Plotter

### Description
Sends the contents of an HPGL file directly to the plotter.

### Method
`plotter.write_file`

### Parameters
#### Path Parameters
- **file_path** (string) - Required - The path to the HPGL file to send.

### Request Example
```python
from chiplotle3 import instantiate_plotters

plotter = instantiate_plotters()[0]

# Send an HPGL file to the plotter
plotter.write_file("artwork.hpgl")
plotter.write_file("design.plt")
```
```

--------------------------------

### Offset a Shape

Source: https://github.com/cyprienh/chiplotle3/blob/main/src/chiplotle3/documentation/chapters/tutorial/shapes.md

Applies an offset transformation to a shape, moving its center. The 'transforms' module must be loaded.

```python
>>> c = shapes.circle(1000)
>>> c.center
Coordinate([0.0, 0.0])
>>> transforms.offset(c, (100, 200))
>>> c.center
Coordinate([100.0, 200.0])
```

--------------------------------

### Save Plotter Commands to HPGL File

Source: https://github.com/cyprienh/chiplotle3/blob/main/src/chiplotle3/documentation/chapters/plotters/index.md

Save collected plotter commands to an HPGL file for later viewing with a compatible viewer or converter.

```python
io.save_hpgl(commands, "diagonal.plt")
```

--------------------------------

### pu_to_mm / pu_to_cm / pu_to_in - Convert from Plotter Units

Source: https://context7.com/cyprienh/chiplotle3/llms.txt

Convert HPGL plotter units back to real-world measurements.

```APIDOC
## pu_to_mm / pu_to_cm / pu_to_in - Convert from Plotter Units

### Description
Convert HPGL plotter units back to real-world measurements.

### Methods
- `pu_to_mm(value)`
- `pu_to_cm(value)`
- `pu_to_in(value)`

### Parameters
#### Path Parameters
- **value** (int) - Required - The measurement in plotter units.

### Request Example
```python
from chiplotle3.tools.measuretools import pu_to_mm, pu_to_cm, pu_to_in
from chiplotle3 import instantiate_plotters

plotter = instantiate_plotters()[0]

# Get plotter dimensions in plotter units
width_pu = plotter.margins.soft.width
height_pu = plotter.margins.soft.height

# Convert to millimeters
width_mm = pu_to_mm(width_pu)
height_mm = pu_to_mm(height_pu)
print(f"Drawing area: {width_mm:.1f}mm x {height_mm:.1f}mm")

# Convert to centimeters
width_cm = pu_to_cm(width_pu)
height_cm = pu_to_cm(height_pu)
print(f"Drawing area: {width_cm:.1f}cm x {height_cm:.1f}cm")

# Convert to inches
width_in = pu_to_in(width_pu)
height_in = pu_to_in(height_pu)
print(f"Drawing area: {width_in:.2f}in x {height_in:.2f}in")
```
```

--------------------------------

### Add Directory to PATH Environment Variable

Source: https://github.com/cyprienh/chiplotle3/blob/main/src/chiplotle3/documentation/chapters/faq/index.md

Temporarily adds a directory to the system's PATH environment variable in Windows. This is useful for making executables in that directory accessible from the command prompt.

```batch
set PATH=%PATH%;C:\path\to\chiplotle_executable
```

--------------------------------

### Scale a Shape

Source: https://github.com/cyprienh/chiplotle3/blob/main/src/chiplotle3/documentation/chapters/tutorial/shapes.md

Applies a scaling transformation to a shape, altering its dimensions. The 'transforms' module must be loaded.

```python
>>> c = shapes.circle(1000)
>>> c.width
2000.0
>>> transforms.scale(c, 2.4)
>>> c.width
4800.0
```

--------------------------------

### Use Paired Apostrophes for Strings

Source: https://github.com/cyprienh/chiplotle3/blob/main/src/chiplotle3/documentation/chapters/contributors/index.md

Delimit strings using paired apostrophes. This is the preferred method for defining string literals.

```default
s = 'foo'
```

--------------------------------

### Eliminate Trivial Slice Indices

Source: https://github.com/cyprienh/chiplotle3/blob/main/src/chiplotle3/documentation/chapters/contributors/index.md

Simplify slice notation by omitting zero indices. Use `s[:4]` instead of `s[0:4]` for cleaner code.

```default
s[:4]
```

--------------------------------

### Rotate Shapes In-Place

Source: https://context7.com/cyprienh/chiplotle3/llms.txt

Rotates a shape in-place around a pivot point using `rotate`. Angle is in radians. Multiple rotations can be applied to create circular patterns.

```python
rect = shapes.rectangle(2000, 500)
rotate(rect, math.pi / 4)

rectangles = Group()
for i in range(8):
    r = shapes.rectangle(2000, 300)
    rotate(r, (math.pi / 4) * i, pivot=(1000, 1000))
    rectangles.append(r)

io.view(rectangles)
```

--------------------------------

### Name Bound Methods in Underscore-Delimited Lowercase

Source: https://github.com/cyprienh/chiplotle3/blob/main/src/chiplotle3/documentation/chapters/contributors/index.md

Bound methods should be named using underscore-delimited lowercase. This convention applies to methods within a class.

```default
def Foo(object):

   def bar_blah(self):
      ...

   def bar_baz(self):
      ...
```

--------------------------------

### Combine Multiple Shapes into a Group

Source: https://context7.com/cyprienh/chiplotle3/llms.txt

Groups collect multiple shapes using `Group` so they can be treated as a single object for transformations. Transformations applied to the group affect all its members.

```python
group = Group()
group.append(shapes.circle(500))
group.append(shapes.rectangle(800, 400))
group.append(shapes.star_outline(600, 600, 5))

rotate(group, math.pi / 6)
scale(group, 2)
offset(group, (3000, 3000))
```

--------------------------------

### Create Ellipse Shape

Source: https://context7.com/cyprienh/chiplotle3/llms.txt

Construct an ellipse with specified width, height, and number of segments. Can create patterns of rotated ellipses.

```python
from chiplotle3 import shapes, Group, Polygon
from chiplotle3.geometry.transforms import rotate
from chiplotle3.tools import io
import math

# Create an ellipse
e = shapes.ellipse(width=5000, height=2000, segments=100)

# Create a pattern of rotated ellipses
pattern = Group()
for i in range(7):
    ellipse = shapes.ellipse(5000, 1000, 500)
    rotate(ellipse, (math.pi * 2 / 7) * i)
    pattern.append(ellipse)

io.view(pattern)
```

--------------------------------

### Rotate a Shape

Source: https://github.com/cyprienh/chiplotle3/blob/main/src/chiplotle3/documentation/chapters/tutorial/shapes.md

Applies a rotation transformation to a shape. The 'transforms' module must be loaded.

```python
>>> r = shapes.rectangle(100, 200)
>>> r.height
200.0
>>> transforms.rotate(r, 3.14 / 4)
>>> r.height
212.16017194397654
```