py_silhouette

https://py-silhouette.readthedocs.io/en/latest
Admin
A Python library for controlling Silhouette series desktop plotters/cutters, providing low-level...
Tokens:8,206
Snippets:44
Trust Score:8.3
Update:1 year ago
Show doc for...
Tokens:
Raw
### Draw a Simple Rectangle with py_silhouette (Quick Example)

Source: https://py-silhouette.readthedocs.io/en/latest/_sources/index.rst

This example demonstrates how to connect to the first available Silhouette device and draw a 20mm x 10mm rectangle using basic move_to commands. It shows the minimal steps required to perform a drawing operation, including moving to a starting point, drawing the rectangle, moving home, and flushing the command buffer.

```Python
from py_silhouette import SilhouetteDevice

# Connect to first available device
d = SilhouetteDevice()

# Move to (10, 10) mm as a starting point without drawing
d.move_to(10, 10, False)

# Draw the rectangle
d.move_to(30, 10, True)
d.move_to(30, 20, True)
d.move_to(10, 20, True)
d.move_to(10, 10, True)

# Finish plotting and return to the home position (don't forget this!)
d.move_home()

# Flush the command buffer and wait for all commands to be acknowledged
# (nothing will happen until this is called)
d.flush()
```

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

### Enumerate and Select Silhouette Devices

Source: https://py-silhouette.readthedocs.io/en/latest/_sources/index.rst

This snippet shows how to discover available Silhouette devices using `enumerate_devices` and allow the user to select a specific device. It addresses the shortcoming of the quick example by providing a way to handle multiple connected devices and initialize a `SilhouetteDevice` instance with specific device parameters.

```Python
from py_silhouette import SilhouetteDevice, enumerate_devices

devices = list(enumerate_devices())
for num, (usb_device, device_params) in enumerate(devices):
    print("{}: {}".format(num, device_params.name))

num = int(input("Choose a device number to use: "))
usb_device, device_params = devices[num]

d = SilhouetteDevice(usb_device, device_params)
```

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

### Python: Cut a Rectangle Path

Source: https://py-silhouette.readthedocs.io/en/latest/index

This example demonstrates how to cut a simple rectangular shape. It uses `SilhouetteDevice.move_to()` to define the path, with `False` for the initial move (pen up) and `True` for subsequent moves (pen down). Finally, `d.move_home()` returns the device to its home position and `d.flush()` ensures all commands are sent.

```Python
d.move_to(10, 10, False)

d.move_to(30, 10, True)
d.move_to(30, 20, True)
d.move_to(10, 20, True)
d.move_to(10, 10, True)

d.move_home()

d.flush()

```

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

### Draw a 20mm x 10mm rectangle with py_silhouette

Source: https://py-silhouette.readthedocs.io/en/latest/index

This Python example demonstrates how to connect to the first available Silhouette device and draw a simple 20mm x 10mm rectangle. It showcases basic plotting operations including moving the plotter head, drawing lines, returning to the home position, and flushing the command buffer to execute the commands.

```Python
from py_silhouette import SilhouetteDevice

# Connect to first available device
d = SilhouetteDevice()

# Move to (10, 10) mm as a starting point without drawing
d.move_to(10, 10, False)

# Draw the rectangle
d.move_to(30, 10, True)
d.move_to(30, 20, True)
d.move_to(10, 20, True)
d.move_to(10, 10, True)

# Finish plotting and return to the home position (don't forget this!)
d.move_home()

# Flush the command buffer and wait for all commands to be acknowledged
# (nothing will happen until this is called)
d.flush()
```

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

### Zero Device on Registration Marks

Source: https://py-silhouette.readthedocs.io/en/latest/_sources/index.rst

This example demonstrates how to use `zero_on_registration_mark` to align the device's coordinate system with printed registration marks. It includes error handling for `RegistrationMarkNotFoundError`, allowing the program to continue without them if marks are not found. This snippet assumes 'd' is an initialized `SilhouetteDevice` object.

```Python
from py_silhouette import RegistrationMarkNotFoundError

try:
    d.zero_on_registration_mark(200, 100)
except RegistrationMarkNotFoundError:
    print("Registration marks not found! Continuing without...")
```

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

### Draw Rectangle and Wait for Plotter Completion

Source: https://py-silhouette.readthedocs.io/en/latest/_sources/index.rst

This example combines drawing a rectangle with waiting for the plotter to complete its operations. After sending drawing commands and flushing the buffer, it uses `get_state` and `DeviceState.moving` to poll the device status, ensuring the program waits until cutting is truly finished. This snippet assumes 'd' is an initialized `SilhouetteDevice` object.

```Python
d.move_to(10, 10, False)

d.move_to(30, 10, True)
d.move_to(30, 20, True)
d.move_to(10, 20, True)
d.move_to(10, 10, True)

d.move_home()

d.flush()

import time
from py_silhouette import DeviceState

while d.get_state() == DeviceState.moving:
    time.sleep(0.5)

print("Cutting complete!")
```

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

### Get SilhouetteDevice State

Source: https://py-silhouette.readthedocs.io/en/latest/index

Obtains the current operational state of the Silhouette device. The returned value is a DeviceState enumeration, indicating what the device is currently doing.

```APIDOC
SilhouetteDevice.get_state() -> DeviceState
```

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

### Get SilhouetteDevice Name

Source: https://py-silhouette.readthedocs.io/en/latest/index

Retrieves the human-readable name and version string reported by the connected Silhouette device. This can be used for diagnostic purposes or user display.

```APIDOC
SilhouetteDevice.get_name() -> str
```

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

### API for Silhouette Device Discovery and Connection

Source: https://py-silhouette.readthedocs.io/en/latest/_sources/index.rst

This section details the API for finding available Silhouette devices, selecting one, and establishing a connection using the `SilhouetteDevice` class. It also covers retrieving basic device information like name and state, and the `DeviceParameters` object used for configuration.

```APIDOC
py_silhouette.enumerate_devices(supported_device_parameters: list[DeviceParameters]) -> list[tuple[usb.core.Device, DeviceParameters]]
  Description: Discovers connected Silhouette devices and returns a list of (USB device, DeviceParameters) tuples.
```

```APIDOC
class SilhouetteDevice
  Description: Represents a connected Silhouette device.
  __init__(usb_device: usb.core.Device, device_params: DeviceParameters)
    usb_device: The USB device object.
    device_params: The parameters for the device.
```

```APIDOC
SilhouetteDevice.params: DeviceParameters
  Description: The DeviceParameters object used to configure the device.
```

```APIDOC
SilhouetteDevice.get_name() -> str
  Description: Requests the device name for diagnostic purposes.
```

```APIDOC
SilhouetteDevice.get_state() -> DeviceState
  Description: Requests the current state of the device.
```

```APIDOC
class DeviceState
  Description: Represents the current state of a Silhouette device.
  Members: (not explicitly listed in source, but implied by ':members:')
```

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

### API Documentation for SilhouetteDevice Tool Parameter Methods

Source: https://py-silhouette.readthedocs.io/en/latest/index

This section provides the API documentation for methods within the `SilhouetteDevice` class used to configure various tool-related parameters such as speed, force, tool diameter, and blade depth. Each method's purpose, parameters, and behavior (e.g., clamping) are detailed.

```APIDOC
Class: SilhouetteDevice
  Methods:
    set_speed(speed: float)
      Description: Set the movement speed of the device in mm/sec.
      Parameters:
        speed (float): The desired speed.
      Notes: Automatically clamped to range specified in `SilhouetteDevice.params.tool_speed_min` and `SilhouetteDevice.params.tool_speed_max`.

    set_force(force: float)
      Description: Set the amount of force to be applied (in grams) when the tool is used.
      Parameters:
        force (float): The desired force in grams.
      Notes: Automatically clamped to range specified in `SilhouetteDevice.params.tool_force_min` and `SilhouetteDevice.params.tool_force_max`.

    set_tool_diameter(diameter: float)
      Description: Inform the plotter of the diameter of a swivelling tool's working point to allow it to adjust tool paths accordingly. This compensates for the blade's position lagging behind the plotter's position when turning corners.
      Parameters:
        diameter (float): Tool swivel mounting diameter.
      Notes: Automatically clamped to range specified in `SilhouetteDevice.params.tool_diameter_min` and `SilhouetteDevice.params.tool_diameter_max`. Strongly recommended for swivelling tools; set to 0.0 for fixed implements (e.g., pens).

    set_depth(depth: float)
      Description: Set the blade depth on devices supporting auto blade.
      Parameters:
        depth (float): The desired blade depth.
      Notes: Automatically clamped to range specified in `SilhouetteDevice.params.tool_depth_min` and `SilhouetteDevice.params.tool_depth_max`.
```

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

### py_silhouette Module-Level API

Source: https://py-silhouette.readthedocs.io/en/latest/genindex

This snippet outlines the top-level functions and constants available directly within the `py_silhouette` module. It includes functions for device enumeration and module-wide configuration parameters.

```APIDOC
Module: py_silhouette
  Functions:
    enumerate_devices()
  Constants:
    SUPPORTED_DEVICE_PARAMETERS
```

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

### APIDOC: py_silhouette Module Overview

Source: https://py-silhouette.readthedocs.io/en/latest/index

Overview of the `py_silhouette` module, its principal class `SilhouetteDevice` for USB plotter connections, and supporting functions like `enumerate_devices()` for device discovery and configuration.

```APIDOC
Module: py_silhouette
  Description: Provides an API for interacting with Silhouette cutting devices.

  Classes:
    SilhouetteDevice
      Description: Represents a connection to a Silhouette plotter via USB.
      Methods:
        move_to(x: float, y: float, pen_down: bool)
          Description: Moves the device to the specified coordinates.
          Parameters:
            x: X-coordinate.
            y: Y-coordinate.
            pen_down: True to cut/draw, False to move without cutting.
        zero_on_registration_mark(width: float, height: float)
          Description: Zeros the device's coordinate system on printed registration marks.
          Parameters:
            width: Expected width of the marked area.
            height: Expected height of the marked area.
          Raises:
            RegistrationMarkNotFoundError: If registration marks are not found.
        set_tool_diameter(diameter: float)
          Description: Informs the device of the tool's diameter for correct corner cutting.
          Parameters:
            diameter: The diameter of the tool.
        set_speed(speed: float)
          Description: Sets the cutting speed of the device.
          Parameters:
            speed: The desired cutting speed.
        set_force(force: float)
          Description: Sets the cutting force applied by the device.
          Parameters:
            force: The desired cutting force.
        flush()
          Description: Blocks until all commands have been received into the plotter's buffer.
        get_state() -> DeviceState
          Description: Returns the current state of the device.
          Returns:
            DeviceState: The current operational state of the device (e.g., moving).

      Properties:
        params: DeviceParameters
          Description: Contains parameters and capabilities of the connected device.
          Properties:
            tool_diameters: dict
              Description: A dictionary of available tool diameters (e.g., {"Knife": value}).
            tool_speed_min: float
              Description: Minimum supported tool speed.
            tool_force_max: float
              Description: Maximum supported tool force.

  Functions:
    enumerate_devices() -> list[tuple[usb_device, DeviceParameters]]
      Description: Discovers and returns a list of available Silhouette devices.
      Returns:
        list: A list of tuples, each containing a USB device object and its DeviceParameters.

  Exceptions:
    RegistrationMarkNotFoundError
      Description: Raised when registration marks are not found during zeroing.

  Enums:
    DeviceState
      Description: Represents the operational states of the device.
      Members:
        moving: The device is currently moving or cutting.

```

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

### Python: Enumerate and Select Silhouette Device

Source: https://py-silhouette.readthedocs.io/en/latest/index

This code snippet demonstrates how to discover available Silhouette devices using `enumerate_devices()` and allows the user to select a specific device from the list. It initializes a `SilhouetteDevice` object with the chosen USB device and its parameters.

```Python
from py_silhouette import SilhouetteDevice, enumerate_devices

devices = list(enumerate_devices())
for num, (usb_device, device_params) in enumerate(devices):
    print("{}: {}".format(num, device_params.name))

num = int(input("Choose a device number to use: "))
usb_device, device_params = devices[num]

d = SilhouetteDevice(usb_device, device_params)

```

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

### API: Device Discovery and Connection for py_silhouette

Source: https://py-silhouette.readthedocs.io/en/latest/index

This section details the API for discovering and connecting to Silhouette devices, including functions for enumerating available devices and the `SilhouetteDevice` class for managing device state and parameters. It also describes the `DeviceState` enum.

```APIDOC
py_silhouette.enumerate_devices() -> list[py_silhouette.SilhouetteDevice]

class py_silhouette.SilhouetteDevice:
  # Attributes
  params: py_silhouette.DeviceParameters

  # Methods
  get_name() -> str
  get_state() -> py_silhouette.DeviceState

class py_silhouette.DeviceState:
  # States
  ready: py_silhouette.DeviceState
  moving: py_silhouette.DeviceState
  unloaded: py_silhouette.DeviceState
  paused: py_silhouette.DeviceState
  unknown: py_silhouette.DeviceState
```

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

### Configure Tool Diameter, Speed, and Force

Source: https://py-silhouette.readthedocs.io/en/latest/_sources/index.rst

This snippet illustrates how to set the tool's diameter for correct corner cutting and configure the plotting speed and force. It uses parameters available from the `DeviceParameters` object (accessed via `d.params`) to ensure optimal performance for the specific tool and device. This snippet assumes 'd' is an initialized `SilhouetteDevice` object.

```Python
d.set_tool_diameter(d.params.tool_diameters["Knife"])

d.set_speed(d.params.tool_speed_min)
d.set_force(d.params.tool_force_max)
```

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

### Initialize SilhouetteDevice for Control

Source: https://py-silhouette.readthedocs.io/en/latest/index

Connects to and controls a specified plotter/cutter. If no arguments are provided, the class will attempt to connect to the first device found by enumerate_devices(), raising a NoDeviceFoundError if none are found.

```APIDOC
py_silhouette.SilhouetteDevice(device=None, device_params=None)
  Parameters:
    device: pyusb.core.Device
      The USB device object for the plotter to control.
    device_params: DeviceParameters
      Definition of the device's key parameters.
```

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

### py_silhouette.DeviceParameters Class API

Source: https://py-silhouette.readthedocs.io/en/latest/genindex

This snippet details the attributes of the `DeviceParameters` class, which encapsulates various physical and operational specifications of a Silhouette cutting device. It includes maximum and minimum values for cutting area, tool depth, diameter, force, and speed, along with product identification.

```APIDOC
Class: py_silhouette.DeviceParameters
  Attributes:
    area_height_max
    area_height_min
    area_width_max
    area_width_min
    product_name
    tool_depth_max
    tool_depth_min
    tool_diameter_max
    tool_diameter_min
    tool_diameters
    tool_force_max
    tool_force_min
    tool_speed_max
    tool_speed_min
```

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

### py_silhouette Library API Reference

Source: https://py-silhouette.readthedocs.io/en/latest/_sources/index.rst

Overview of the core classes, functions, and data structures within the `py_silhouette` module for controlling Silhouette plotters. It details the main `SilhouetteDevice` class and its methods, along with supporting functions and data types.

```APIDOC
Module: py_silhouette

Class: SilhouetteDevice
  Description: Represents a connection to a Silhouette plotter via USB.
  Methods:
    __init__(usb_device=None, device_params=None): Initializes a connection to a device.
    move_to(x: float, y: float, draw: bool): Moves the plotter head to a specified (x, y) coordinate. 'draw' indicates whether to draw during the move.
    zero_on_registration_mark(width: float, height: float): Zeros the device's coordinate system on printed registration marks of a given area.
    set_tool_diameter(diameter: float): Informs the device of the tool's diameter for correct corner cutting.
    set_speed(speed: float): Sets the plotting speed.
    set_force(force: float): Sets the plotting force.
    get_state(): Returns the current state of the device.
    flush(): Flushes the command buffer and waits for commands to be acknowledged.
    move_home(): Returns the plotter to the home position.
  Attributes:
    params: DeviceParameters - Contains parameters specific to the connected device.

Function: enumerate_devices()
  Description: Discovers and returns a list of available Silhouette devices.
  Returns: list of (usb_device, device_params) tuples.

Exception: RegistrationMarkNotFoundError
  Description: Raised when registration marks are not found during zeroing.

Class: DeviceParameters
  Description: Contains various parameters and capabilities of a Silhouette device.
  Attributes:
    name: str - The name of the device.
    tool_diameters: dict - Dictionary of tool diameters (e.g., {"Knife": diameter_value}).
    tool_speed_min: float - Minimum supported tool speed.
    tool_force_max: float - Maximum supported tool force.

Enum: DeviceState
  Description: Represents the operational state of the Silhouette device.
  States:
    moving: Indicates the device is currently performing a movement or plotting operation.
```

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

### API for Device Parameters and Supported Device Data

Source: https://py-silhouette.readthedocs.io/en/latest/_sources/index.rst

This section provides access to predefined device parameters for widely used Silhouette devices via `SUPPORTED_DEVICE_PARAMETERS` and details the structure of the `DeviceParameters` class, which defines device characteristics like USB identifiers and plotter dimensions.

```APIDOC
SUPPORTED_DEVICE_PARAMETERS: list[DeviceParameters]
  Description: A list of DeviceParameters describing supported devices. Currently verified for Silhouette Portrait v1.
```

```APIDOC
class DeviceParameters
  Description: Defines parameters for a particular supported device, including USB interface identifiers, plotter dimensions, and tool support.
  Members: (not explicitly listed in source, but implied by ':members:')
```

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

### API Documentation for SilhouetteDevice.zero_on_registration_mark

Source: https://py-silhouette.readthedocs.io/en/latest/index

Detailed API reference for the `zero_on_registration_mark` method of the `SilhouetteDevice` class, which allows for precise coordinate system zeroing using printed registration marks. It compensates for page misalignments and blocks until marks are found or not, raising `RegistrationMarkNotFoundError` if unsuccessful.

```APIDOC
Class: SilhouetteDevice
Method: zero_on_registration_mark
Signature: zero_on_registration_mark(width: float, height: float, box_size: float = 5.0, line_thickness: float = 0.5, line_length: float = 20.0, search: bool = True)
Description: Zero coordinate system and compensate for small page misalignments using registration marks printed on the page. If the registration marks are not found, RegistrationMarkNotFoundError is raised. This command will block until the registration marks have been found or not. The registration settings will be retained until the current page is ejected from the machine. As a side effect of calling this command, the tool speed will be set to its maximum.
Parameters:
  width, height: float
    The size of the area the registration mark covers in mm. Warning: Take care that the right-most registration mark is not too close to the right-hand extreme of the machine. The registration sensor is mounted at the very left side of the carriage so it will need to move further than it would when plotting on that corner of the page. The plotter does not have a ‘right’ end-stop and may hit the end of its axis.
  box_size: float (default 5.0)
    The size of the black square in the top-left registration mark (mm). Currently must be set to 5mm (the default).
  line_thickness: float (default 0.5)
    The thickness of the registration lines (mm). Default of 0.5 mm is known to work well.
  line_length: float (default 20.0)
    The length the registration lines (mm). Default of 20 mm is known to work well.
  search: bool (default True)
    If true, the device will start searching for the registration mark automatically, starting at the device home position. If False the device should first be positioned with the tool over the black square. In practice this is very difficult to achieve so most users will want to leave this setting in its default mode (True).
```

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

### API: Device Parameters and Tools for py_silhouette

Source: https://py-silhouette.readthedocs.io/en/latest/index

This section details the `SUPPORTED_DEVICE_PARAMETERS` constant and the `DeviceParameters` class, which defines the various physical and operational limits and characteristics of a Silhouette device, such as dimensions, force, and speed ranges.

```APIDOC
py_silhouette.SUPPORTED_DEVICE_PARAMETERS: dict

class py_silhouette.DeviceParameters:
  # Attributes
  product_name: str
  usb_vendor_id: int
  usb_product_id: int
  area_width_min: float
  area_width_max: float
  area_height_min: float
  area_height_max: float
  tool_diameters: list[float]
  tool_force_min: float
  tool_force_max: float
  tool_speed_min: float
  tool_speed_max: float
  tool_diameter_min: float
  tool_diameter_max: float
  tool_depth_min: float
  tool_depth_max: float
```

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

### py_silhouette.SilhouetteDevice Class API

Source: https://py-silhouette.readthedocs.io/en/latest/genindex

This snippet outlines the methods and attributes of the `SilhouetteDevice` class, which serves as the primary interface for controlling a Silhouette cutting device. It includes functions for managing device state, movement, and setting cutting parameters like depth, force, and speed.

```APIDOC
Class: py_silhouette.SilhouetteDevice
  Methods:
    flush()
    get_name()
    get_state()
    move_home()
    move_to()
    set_depth()
    set_force()
    set_speed()
    set_tool_diameter()
  Attributes:
    params
```

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

### py_silhouette.SUPPORTED_DEVICE_PARAMETERS Constant

Source: https://py-silhouette.readthedocs.io/en/latest/index

Describes the py_silhouette.SUPPORTED_DEVICE_PARAMETERS constant, which is a list of DeviceParameters objects for widely used Silhouette devices. At the time of writing, only support for the Silhouette Portrait v1 has been verified.

```APIDOC
py_silhouette.SUPPORTED_DEVICE_PARAMETERS:
  Type: list of py_silhouette.DeviceParameters
  Description: A list of DeviceParameters objects describing a particular supported device.
  Note: At the time of writing, only support for the Silhouette Potrait v1 has been verified.
```

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

### py_silhouette Library Exception API Reference

Source: https://py-silhouette.readthedocs.io/en/latest/index

Detailed API documentation for the custom exception classes defined in the py_silhouette library, outlining their purpose and specific conditions under which they are raised.

```APIDOC
py_silhouette.DeviceError:
  Description: Baseclass for all py_silhouette hardware related errors.

py_silhouette.NoDeviceFoundError:
  Description: No connected devices were found.

py_silhouette.RegistrationMarkNotFoundError:
  Description: The registration mark could not be found.

py_silhouette.AutoBladeNotSupportedError:
  Description: Thrown when SilhouetteDevice.set_depth() is called on a device without auto blade support.
```

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

### Access SilhouetteDevice Parameters

Source: https://py-silhouette.readthedocs.io/en/latest/index

Provides access to the DeviceParameters object associated with the SilhouetteDevice instance. This object contains useful information about the shape and size of media and tools supported by the connected device.

```APIDOC
SilhouetteDevice.params: DeviceParameters
```

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

### API: Plotter Origin and Tool Parameter Settings for py_silhouette

Source: https://py-silhouette.readthedocs.io/en/latest/index

This section covers `SilhouetteDevice` methods for setting the plotter's origin and configuring tool-specific parameters such as speed, force, diameter, and depth. These methods allow fine-grained control over the cutting or plotting process.

```APIDOC
class py_silhouette.SilhouetteDevice:
  # Methods for Plotter Origin
  zero_on_registration_mark() -> None

  # Methods for Tool Parameters
  set_speed(speed: float) -> None
  set_force(force: float) -> None
  set_tool_diameter(diameter: float) -> None
  set_depth(depth: float) -> None
```

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

### Python: Zero Device on Registration Marks

Source: https://py-silhouette.readthedocs.io/en/latest/index

This snippet attempts to zero the device's coordinate system based on printed registration marks using `SilhouetteDevice.zero_on_registration_mark()`. It includes error handling for `RegistrationMarkNotFoundError` if marks are not detected, allowing the process to continue without them.

```Python
from py_silhouette import RegistrationMarkNotFoundError

try:
    d.zero_on_registration_mark(200, 100)
except RegistrationMarkNotFoundError:
    print("Registration marks not found! Continuing without...")

```

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

### Python: Configure Cutting Speed and Force

Source: https://py-silhouette.readthedocs.io/en/latest/index

This snippet configures the cutting speed and force for the Silhouette device. It uses the minimum tool speed and maximum tool force available from the device's parameters (`d.params`) to set these values via `SilhouetteDevice.set_speed()` and `SilhouetteDevice.set_force()`.

```Python
d.set_speed(d.params.tool_speed_min)
d.set_force(d.params.tool_force_max)

```

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

### API: SilhouetteDevice.move_to Method

Source: https://py-silhouette.readthedocs.io/en/latest/index

Moves the plotter to an absolute page position (x, y) in mm, with an option to engage or disengage the tool during movement. Coordinates are relative to the device's home position or a registration mark if `zero_on_registration_mark` was used. Call `flush()` to ensure the command is sent and `move_home()` after a sequence of calls.

```APIDOC
SilhouetteDevice.move_to(x: float, y: float, use_tool: bool)
  Description: Move the plotter, optionally with the tool engaged.
  Parameters:
    x, y (float):
      Absolute page position in mm.
      These values will be clamped between 0 and the maximum page width and height.
      It is the caller’s responsibility to sensibly clip the input to prevent crashes.
      Coordinates start from the device’s home position, or relative to the top-left corner of the registration mark if zeroed.
    use_tool (bool):
      If True, the tool will be applied during the movement. If False, the tool will be lifted.
  Notes:
    Call flush() to ensure this command has arrived at the device.
    After completing a sequence of move_to commands, always use move_home() to return the plotter to the home position and notify the device that plotting has finished.
```

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

### API for Performing Plotting Operations

Source: https://py-silhouette.readthedocs.io/en/latest/_sources/index.rst

This API outlines the sequence of operations for plotting, including moving the tool to specific coordinates, returning to the home position, and flushing commands to the device to ensure execution.

```APIDOC
SilhouetteDevice.move_to(x: float, y: float) -> None
  Description: Moves the tool to the specified coordinates.
```

```APIDOC
SilhouetteDevice.move_home() -> None
  Description: Moves the tool to the device's home position.
```

```APIDOC
SilhouetteDevice.flush() -> None
  Description: Flushes pending commands to the device.
```

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

### Python: Wait for Device Cutting Completion

Source: https://py-silhouette.readthedocs.io/en/latest/index

This code snippet shows how to wait until the Silhouette device has finished its cutting operation. It continuously checks the device's state using `d.get_state()` and pauses until the state is no longer `DeviceState.moving`, indicating completion.

```Python
import time
from py_silhouette import DeviceState

while d.get_state() == DeviceState.moving:
    time.sleep(0.5)

print("Cutting complete!")

```

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

### py_silhouette.DeviceState Class API

Source: https://py-silhouette.readthedocs.io/en/latest/genindex

This snippet describes the attributes of the `DeviceState` class, which represents the current operational status of a connected Silhouette cutting device. It provides information on whether the device is moving, paused, or ready for operation.

```APIDOC
Class: py_silhouette.DeviceState
  Attributes:
    moving
    paused
    ready
```

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

### API for Setting Tool Parameters

Source: https://py-silhouette.readthedocs.io/en/latest/_sources/index.rst

This section describes API methods for adjusting plotting speed, force, tool diameter, and auto blade depth. These parameters are crucial for optimizing plotting based on the tool and material in use.

```APIDOC
SilhouetteDevice.set_speed(speed: float) -> None
  Description: Sets the plotting speed.
```

```APIDOC
SilhouetteDevice.set_force(force: int) -> None
  Description: Sets the plotting force.
```

```APIDOC
SilhouetteDevice.set_tool_diameter(diameter: float) -> None
  Description: Sets the tool diameter for toolpath compensation.
```

```APIDOC
SilhouetteDevice.set_depth(depth: int) -> None
  Description: Automatically sets the blade depth for devices with an auto blade.
```

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

### Py-Silhouette Library Exception Classes

Source: https://py-silhouette.readthedocs.io/en/latest/_sources/index.rst

This section lists the specific exception classes that may be raised by the `py-silhouette` library during device interaction, enabling developers to implement robust error handling mechanisms.

```APIDOC
exception DeviceError
  Description: Base exception for device-related errors.
```

```APIDOC
exception NoDeviceFoundError
  Description: Raised when no Silhouette device is found.
```

```APIDOC
exception RegistrationMarkNotFoundError
  Description: Raised when registration marks cannot be found.
```

```APIDOC
exception AutoBladeNotSupportedError
  Description: Raised when auto blade functionality is not supported by the device.
```

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

### Enumerate Connected Silhouette Devices

Source: https://py-silhouette.readthedocs.io/en/latest/index

Generates pairs of device and device parameters for all currently connected Silhouette devices. This function allows filtering by providing a list of supported device parameters to include in the enumeration.

```APIDOC
py_silhouette.enumerate_devices(supported_device_parameters=SUPPORTED_DEVICE_PARAMETERS)
  Parameters:
    supported_device_parameters: list[DeviceParameters, ...]
      An optional list of DeviceParameters objects for the types of devices to include in the enumeration. Defaults to all supported devices.
```

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

### py_silhouette Error Classes API

Source: https://py-silhouette.readthedocs.io/en/latest/genindex

This snippet lists the custom error classes defined within the `py_silhouette` library. These exceptions are raised to indicate specific issues encountered during device interaction, such as a device not being found, unsupported auto-blade features, or failure to detect registration marks.

```APIDOC
Error Classes:
  AutoBladeNotSupportedError
  DeviceError
  NoDeviceFoundError
  RegistrationMarkNotFoundError
```

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

### API for Configuring Plotter Origin

Source: https://py-silhouette.readthedocs.io/en/latest/_sources/index.rst

This API allows setting the coordinate system origin for plotting. Users can either use the device's 'home' position or zero the axes based on registration marks printed on the page.

```APIDOC
SilhouetteDevice.zero_on_registration_mark() -> None
  Description: Zeros the plotting axes on registration marks printed on the page.
```

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

### py_silhouette.DeviceParameters Class Definition

Source: https://py-silhouette.readthedocs.io/en/latest/index

Defines the DeviceParameters class, which encapsulates the physical and operational characteristics of a Silhouette device. This includes USB interface identifiers, plotter dimensions, and out-of-the-box tool support. The class is generated by attrs.

```APIDOC
class py_silhouette.DeviceParameters(
  product_name: str,
  usb_vendor_id: int,
  usb_product_id: int,
  area_width_min: float,
  area_width_max: float,
  area_height_min: float,
  area_height_max: float,
  tool_diameters: dict = _Nothing.NOTHING,
  tool_force_min: float = 7.0,
  tool_force_max: float = 231.0,
  tool_speed_min: float = 100.0,
  tool_speed_max: float = 1000.0,
  tool_diameter_min: float = 0.0,
  tool_diameter_max: float = 2.3,
  tool_depth_min: Optional[float] = None,
  tool_depth_max: Optional[float] = None
):
  Description: Method generated by attrs for class DeviceParameters.

  Attributes:
    product_name (str): Human readable product name for the device supported by this class.
    usb_vendor_id (int): The USB Vendor ID used by device.
    usb_product_id (int): The USB Product ID used by device.
    area_width_min (float): Minimum width for valid plot areas (mm).
    area_width_max (float): Maximum width for valid plot areas (mm).
    area_height_min (float): Minimum height for valid plot areas (mm).
    area_height_max (float): Maximum height for valid plot areas (mm).
    tool_diameters (dict): A dictionary mapping from tool name to tool diameter (in mm) for all tools which ship with or are available for this device.
    tool_force_min (float): Lowest force which may be applied by the machine (in grams).
    tool_force_max (float): Highest force which may be applied by the machine (in grams).
    tool_speed_min (float): Lowest speed at which the machine can move (mm/sec).
    tool_speed_max (float): Highest speed at which the machine can move (mm/sec).
    tool_diameter_min (float): Lowest valid tool diameter (mm).
    tool_diameter_max (float): Highest valid tool diameter (mm).
    tool_depth_min (Optional[float]): Shortest valid knife setting, or None if automatic depth setting is not possible for this device.
    tool_depth_max (Optional[float]): Longest valid knife setting, or None if automatic depth setting is not possible for this device.
```

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

### API: SilhouetteDevice.flush Method

Source: https://py-silhouette.readthedocs.io/en/latest/index

Ensures all outstanding commands sent to the Silhouette device have been processed. This method blocks execution until all commands are complete, guaranteeing that previous commands have arrived at the device.

```APIDOC
SilhouetteDevice.flush()
  Description: Ensure all outstanding commands have been sent. Blocks until complete.
```

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

### API: Exception Handling for py_silhouette

Source: https://py-silhouette.readthedocs.io/en/latest/index

This section lists the custom exception classes defined in `py_silhouette` for handling specific error conditions that may arise during device operation, such as general device errors, no device found, registration mark issues, or unsupported auto-blade features.

```APIDOC
class py_silhouette.DeviceError(Exception):
  pass

class py_silhouette.NoDeviceFoundError(py_silhouette.DeviceError):
  pass

class py_silhouette.RegistrationMarkNotFoundError(py_silhouette.DeviceError):
  pass

class py_silhouette.AutoBladeNotSupportedError(py_silhouette.DeviceError):
  pass
```

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

### Define Silhouette Device States

Source: https://py-silhouette.readthedocs.io/en/latest/index

An enumeration representing the possible operational states of a Silhouette device. This class defines various states such as ready, moving, unloaded, paused, and an unknown state for unrecognised conditions.

```APIDOC
py_silhouette.DeviceState(value)
  ready = b'0'
    The device is ready to begin plotting.
  moving = b'1'
    The plotter is busy plotting or moving.
  unloaded = b'2'
    Idle with no media loaded.
  paused = b'3'
    The pause button has been pressed.
  unknown = None
    Unrecognised device state; probably an error.
```

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

### API: Plotting Operations for py_silhouette

Source: https://py-silhouette.readthedocs.io/en/latest/index

This section describes the `SilhouetteDevice` methods for controlling plotting movements, including moving to specific coordinates, returning to the home position, and flushing pending commands to the device. These are essential for executing plotting tasks.

```APIDOC
class py_silhouette.SilhouetteDevice:
  # Methods for Plotting
  move_to(x: float, y: float) -> None
  move_home() -> None
  flush() -> None
```

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

### API: SilhouetteDevice.move_home Method

Source: https://py-silhouette.readthedocs.io/en/latest/index

Moves the plotter carriage to the home position (or top-left registration mark if zeroed) with the tool disengaged. This method is expected to be the final command after a series of `move_to` calls to signal the end of plotting. Failure to use it may cause command delays.

```APIDOC
SilhouetteDevice.move_home()
  Description: Move the carriage to the home position (or to the top-left registration mark if zeroed) with the tool disengaged.
  Notes:
    The plotter expects this to be the final command received at the end of a sequence of move_to() calls.
    If this command is not used, the final command sent will be delayed for a short while.
    Call flush() to ensure this command has arrived at the device.
```

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

### Python: Set Tool Diameter for Correct Cutting

Source: https://py-silhouette.readthedocs.io/en/latest/index

This code sets the tool's diameter using `SilhouetteDevice.set_tool_diameter()`. This is crucial for ensuring that corners are cut correctly, retrieving the appropriate diameter from the device's parameters (`d.params.tool_diameters`).

```Python
d.set_tool_diameter(d.params.tool_diameters["Knife"])

```
Tokens:
Raw