klipper/docs/Exclude_Object.md

Exclude Objects

The [exclude_object] module allows Klipper to exclude objects while a print is in progress. To enable this feature include an exclude_object config section (also see the command reference and sample-macros.cfg file for a Marlin/RepRapFirmware compatible M486 G-Code macro.)

Unlike other 3D printer firmware options, a printer running Klipper utilizes a suite of components and users have many options to choose from. Therefore, in order to provide a a consistent user experience, the [exclude_object] module will establish a contract or API of sorts. The contract covers the contents of the gcode file, how the internal state of the module is controlled, and how that state is provided to clients.

Workflow Overview

A typical workflow for printing a file might look like this:

1. Slicing is completed and the file is uploaded for printing. During the upload, the file is processed and [exclude_object] markers are added to the file. Alternately, slicers may be configured to prepare object exclusion markers natively, or in it's own pre-processing step.
2. When printing starts, Klipper will reset the [exclude_object] status.
3. When Klipper processes the EXCLUDE_OBJECT_DEFINE block, it will update the status with the known objects and pass it on to clients.
4. The client may use that information to present a UI to the user so that progress can be tracked. Klipper will update the status to include the currently printing object which the client can use for display purposes.
5. If the user requests that an object be cancelled, the client will issue an EXCLUDE_OBJECT NAME=<name> command to Klipper.
6. When Klipper process the command, it will add the object to the list of excluded objects and update the status for the client.
7. The client will receive the updated status from Klipper and can use that information to reflect the object's status in the UI.
8. When printing finishes, the [exclude_object] status will continue to be available until another action resets it.

The GCode File

The specialized gcode processing needed to support excluding objects does not fit into Klipper's core design goals. Therefore, this module requires that the file is processed before being sent to Klipper for printing. Using a post-process script in the slicer or having middleware process the file on upload are two possibilities for preparing the file for Klipper. A reference post-processing script is available both as an executable and a python library, see cancelobject-preprocessor.

Object Definitions

The EXCLUDE_OBJECT_DEFINE command is used to provide a summary of each object in the gcode file to be printed. Provides a summary of an object in the file. Objects don't need to be defined in order to be referenced by other commands. The primary purpose of this command is to provide information to the UI without needing to parse the entire gcode file.

Object definitions are named, to allow users to easily select an object to be excluded, and additional metadata may be provided to allow for graphical cancellation displays. Currently defined metadata includes a CENTER X,Y coordinate, and a POLYGON list of X,Y points representing a minimal outline of the object. This could be a simple bounding box, or a complicated hull for showing more detailed visualizations of the printed objects. Especially when gcode files include multiple parts with overlapping bounding regions, center points become hard to visually distinguish. POLYGONS must be a json-compatible array of point [X,Y] tuples without whitespace. Additional parameters will be saved as strings in the object definition and provided in status updates.

EXCLUDE_OBJECT_DEFINE NAME=calibration_pyramid CENTER=50,50 POLYGON=[[40,40],[50,60],[60,40]]

All available G-Code commands are documented in the G-Code Reference

Status Information

The state of this module is provided to clients by the exclude_object status.

The status is reset when:

• The Klipper firmware is restarted.
• There is a reset of the [virtual_sdcard]. Notably, this is reset by Klipper at the start of a print.
• When an EXCLUDE_OBJECT_DEFINE RESET=1 command is issued.

The list of defined objects is represented in the exclude_object.objects status field. In a well defined gcode file, this will be done with EXCLUDE_OBJECT_DEFINE commands at the beginning of the file. This will provide clients with object names and coordinates so the UI can provide a graphical representation of the objects if desired.

As the print progresses, the exclude_object.current_object status field will be updated as Klipper processes EXCLUDE_OBJECT_START and EXCLUDE_OBJECT_END commands. The current_object field will be set even if the object has been excluded. Undefined objects marked with a EXCLUDE_OBJECT_START will be added to the known objects to assist in UI hinting, without any additional metadata.

As EXCLUDE_OBJECT commands are issued, the list of excluded objects is provided in the exclude_object.excluded_objects array. Since Klipper looks ahead to process upcoming gcode, there may be a delay between when the command is issued and when the status is updated.