vpype_gscrib.renderer.tools

Tool activation and parameter control.

This module provides implementations for different machine tools such as lasers, spindles, and other end effectors. Each implementation handles tool initialization, activation, power control, and shutdown, generating the corresponding G-code commands for various tool types and behaviors.

class vpype_gscrib.renderer.tools.AdaptiveBeamTool

Bases: BaseTool

Beam implementation with height map-based power modulation.

This class handles basic operations for controlling the machine’s beam tool with power adjustments based on a height map. All work movements are processed with the height map to modify beam power, which enables various applications such as:

  • Photo engraving: Converts grayscale images into varying beam intensities to create detailed photographic engravings.

  • Surface processing: Maintains consistent cutting/engraving depth on uneven surfaces by automatically modulating beam power.

  • Material adaptation: Maintains consistent cutting depth across materials with varying thickness or density.

  • Artistic effects: Uses height maps as power maps to create controlled variations in cutting or engraving intensity.

activate(ctx: GContext)

Activate the beam tool.

Generates G-code commands to initialize and prepare the beam tool for operation, setting initial power level to zero.

Parameters:

ctx (GContext) – The G-code generation context

deactivate(ctx: GContext)

Deactivate the beam tool.

Generates G-code commands to completely shut down the beam tool.

Parameters:

ctx (GContext) – The G-code generation context

get_trace_params(ctx: GContext, x: float, y: float) → dict

Sets the beam power according to the height map.

This method sets the appropriate beam power parameter for the current position being traced by querying the height map. The power level is adjusted based on the height value at the specified coordinates and the heightmap scaling factor.

Parameters:

  • ctx (GContext) – Current rendering context

  • x (float) – Target X coordinate of the movement

  • y (float) – Target Y coordinate of the movement

Returns:

Dictionary with the power parameter set (S).

Return type:

dict

power_off(ctx: GContext)

Power off the beam tool.

Generates G-code commands to set the beam tool to its inactive power level and wait for the tool to cool down.

Parameters:

ctx (GContext) – The G-code generation context

power_on(ctx: GContext)

Power on the beam tool.

Generates G-code commands to set the beam tool to its working power level and wait for the tool to warm up.

Parameters:

ctx (GContext) – The G-code generation context

class vpype_gscrib.renderer.tools.BaseTool

Bases: ABC

Base class for tool implementations.

This abstract base class defines the interface for controlling various machine tools like lasers, spindles, or other end effectors. It handles tool initialization, power control, and shutdown.

Different tools may have different activation patterns:

  • A spindle tool may start rotating during activation, but power on/off won’t affect its state

  • A laser tool may initialize at zero power during activation, and power on/off will control the beam intensity

  • A pen tool might not need activation or power on/off

abstractmethod activate(ctx: GContext)

Prepare the tool for operation.

Generates G-code commands to initialize and prepare the tool before its use. This might include setting up tool-specific parameters (spindle speed, initial power, etc) and waiting for the tool to warm up.

Parameters:

ctx (GContext) – The G-code generation context

abstractmethod deactivate(ctx: GContext)

Perform tool shutdown operations.

Generates G-code commands to completely shut down the tool system. For exemple, this might include stopping a spindle or turning off a laser.

Parameters:

ctx (GContext) – The G-code generation context

get_trace_params(ctx: GContext, x: float, y: float) → dict

Get tool-specific parameters for trace movements.

This method allows tools to inject additional parameters into movement commands for work operations. The parameters returned by this method will be merged with the basic movement parameters (X, Y, Z, F) when generating G1 commands.

For example:

  • Laser tools might add power parameters (S)

  • Extruder tools might add extrusion parameters (E)

Parameters:

  • ctx (GContext) – Current rendering context

  • x (float) – Target X coordinate of the movement

  • y (float) – Target Y coordinate of the movement

Returns:

Tool-specific parameters or an empty dict if none.

Return type:

dict

Example

A laser tool might return {‘S’: 1000} to set laser power to 1000 during trace movements, resulting in a G1 command like:

G1 X100 Y100 F500 S1000

abstractmethod power_off(ctx: GContext)

Set the tool to its inactive state.

Generates G-code commands to set the tool to its non-working state while keeping the system active. The behavior varies by tool type.

Parameters:

ctx (GContext) – The G-code generation context

abstractmethod power_on(ctx: GContext)

Set the tool to its active working state.

Generates G-code commands to set the tool to its working configuration. This might include setting the beam intensity, lowering the pen, etc.

Parameters:

ctx (GContext) – The G-code generation context

class vpype_gscrib.renderer.tools.BeamTool

Bases: BaseTool

Beam tool implementation.

This class handles operations for a beam tool, such as a laser, including activation, power control, and deactivation.

activate(ctx: GContext)

Activate the beam tool.

Generates G-code commands to initialize and prepare the beam tool for operation, setting initial power level to zero.

Parameters:

ctx (GContext) – The G-code generation context

deactivate(ctx: GContext)

Deactivate the beam tool.

Generates G-code commands to completely shut down the beam tool.

Parameters:

ctx (GContext) – The G-code generation context

power_off(ctx: GContext)

Power off the beam tool.

Generates G-code commands to set the beam tool to its inactive power level and wait for the tool to cool down.

Parameters:

ctx (GContext) – The G-code generation context

power_on(ctx: GContext)

Power on the beam tool.

Generates G-code commands to set the beam tool to its working power level and wait for the tool to warm up.

Parameters:

ctx (GContext) – The G-code generation context

class vpype_gscrib.renderer.tools.BladeTool

Bases: BaseTool

Blade tool implementation.

This class handles operations for a blade tool, which does not require activation or power control. This is currently a no-op implementation.

activate(ctx: GContext)

Prepare the tool for operation.

Generates G-code commands to initialize and prepare the tool before its use. This might include setting up tool-specific parameters (spindle speed, initial power, etc) and waiting for the tool to warm up.

Parameters:

ctx (GContext) – The G-code generation context

deactivate(ctx: GContext)

Perform tool shutdown operations.

Generates G-code commands to completely shut down the tool system. For exemple, this might include stopping a spindle or turning off a laser.

Parameters:

ctx (GContext) – The G-code generation context

power_off(ctx: GContext)

Set the tool to its inactive state.

Generates G-code commands to set the tool to its non-working state while keeping the system active. The behavior varies by tool type.

Parameters:

ctx (GContext) – The G-code generation context

power_on(ctx: GContext)

Set the tool to its active working state.

Generates G-code commands to set the tool to its working configuration. This might include setting the beam intensity, lowering the pen, etc.

Parameters:

ctx (GContext) – The G-code generation context

class vpype_gscrib.renderer.tools.ExtruderTool

Bases: BaseTool

Extruder tool implementation for 3D printing.

This class handles filament retraction and extrusion for an extruder tool that does not require temperature control.

activate(ctx: GContext)

Initialize and activate the extruder tool.

Sets up the initial state of the extruder including:

  • Configuring absolute extrusion mode

  • Zeroing the extruder position

Parameters:

ctx (GContext) – Current rendering context

deactivate(ctx: GContext)

Perform tool shutdown operations.

Generates G-code commands to completely shut down the tool system. For exemple, this might include stopping a spindle or turning off a laser.

Parameters:

ctx (GContext) – The G-code generation context

get_trace_params(ctx: GContext, x: float, y: float) → dict

Compute and set extruder parameters for work moves

Computes the required extruder position based on the target coordinates and current position.

Parameters:

  • ctx (GContext) – Current rendering context

  • x (float) – Target X coordinate of the movement

  • y (float) – Target Y coordinate of the movement

Returns:

Dictionary with the extruder position set (E).

Return type:

dict

power_off(ctx: GContext)

Retract filament after tracing a path.

Retracts the filament by the configured distance to prevent oozing when moving without printing.

Parameters:

ctx (GContext) – Current rendering context

power_on(ctx: GContext)

Recover filament before tracing a path.

Moves the filament forward by the configured retraction distance to prepare for printing.

Parameters:

ctx (GContext) – Current rendering context

class vpype_gscrib.renderer.tools.HeatedExtruderTool

Bases: BaseTool

Heated extruder tool implementation for 3D printing.

This class handles operations for an extruder tool, including temperature control, filament retraction, and extrusion.

activate(ctx: GContext)

Initialize and activate the extruder tool.

Sets up the initial state of the extruder including:

  • Setting the hotend temperature

  • Waiting for the hotend to reach target temperature

  • Configuring absolute extrusion mode

  • Zeroing the extruder position

Parameters:

ctx (GContext) – Current rendering context

deactivate(ctx: GContext)

Deactivate the extruder tool.

Turns off the hotend when the tool is no longer needed.

Parameters:

ctx (GContext) – Current rendering context

get_trace_params(ctx: GContext, x: float, y: float) → dict

Compute and set extruder parameters for work moves

Computes the required extruder position based on the target coordinates and current position.

Parameters:

  • ctx (GContext) – Current rendering context

  • x (float) – Target X coordinate of the movement

  • y (float) – Target Y coordinate of the movement

Returns:

Dictionary with the extruder position set (E).

Return type:

dict

power_off(ctx: GContext)

Retract filament after tracing a path.

Retracts the filament by the configured distance to prevent oozing when moving without printing.

Parameters:

ctx (GContext) – Current rendering context

power_on(ctx: GContext)

Recover filament before tracing a path.

Moves the filament forward by the configured retraction distance to prepare for printing.

Parameters:

ctx (GContext) – Current rendering context

class vpype_gscrib.renderer.tools.MarkerTool

Bases: BaseTool

Marker tool implementation.

This class handles operations for a marker tool (pen, brush, etc), which does not require activation or power control. This is currently a no-op implementation.

activate(ctx: GContext)

Prepare the tool for operation.

Generates G-code commands to initialize and prepare the tool before its use. This might include setting up tool-specific parameters (spindle speed, initial power, etc) and waiting for the tool to warm up.

Parameters:

ctx (GContext) – The G-code generation context

deactivate(ctx: GContext)

Perform tool shutdown operations.

Generates G-code commands to completely shut down the tool system. For exemple, this might include stopping a spindle or turning off a laser.

Parameters:

ctx (GContext) – The G-code generation context

power_off(ctx: GContext)

Set the tool to its inactive state.

Generates G-code commands to set the tool to its non-working state while keeping the system active. The behavior varies by tool type.

Parameters:

ctx (GContext) – The G-code generation context

power_on(ctx: GContext)

Set the tool to its active working state.

Generates G-code commands to set the tool to its working configuration. This might include setting the beam intensity, lowering the pen, etc.

Parameters:

ctx (GContext) – The G-code generation context

class vpype_gscrib.renderer.tools.SpindleTool

Bases: BaseTool

Spindle tool implementation.

This class handles operations for a spindle tool, including activation and deactivation.

activate(ctx: GContext)

Activate the spindle tool.

Generates G-code commands to initialize and prepare the spindle tool for operation, setting the spindle speed, operation mode (clockwise or counterclockwise), turning it on and waiting for the tool to warm-up.

Parameters:

ctx (GContext) – The G-code generation context

deactivate(ctx: GContext)

Deactivate the spindle tool.

Generates G-code commands to completely shut down the spindle tool and wait for it to cool stop.

Parameters:

ctx (GContext) – The G-code generation context

power_off(ctx: GContext)

Set the tool to its inactive state.

Generates G-code commands to set the tool to its non-working state while keeping the system active. The behavior varies by tool type.

Parameters:

ctx (GContext) – The G-code generation context

power_on(ctx: GContext)

Set the tool to its active working state.

Generates G-code commands to set the tool to its working configuration. This might include setting the beam intensity, lowering the pen, etc.

Parameters:

ctx (GContext) – The G-code generation context

class vpype_gscrib.renderer.tools.ToolFactory

Bases: object

A factory for creating tool managers.

This factory creates specialized tool manager instances that handle different types of CNC machine tools and their operations. Each tool manager controls specific aspects of its corresponding tool such as power settings, speed, and operational states.

classmethod create(tool_type: ToolType) → BaseTool

Create a new tool manger instance.

Parameters:

tool_type (ToolType) – Tool type.

Returns:

Tool manger instance.

Return type:

BaseTool

Raises:

KeyError – If type is not valid.