[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
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
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.
A typical workflow for printing a file might look like this:
- 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.
- When printing starts, Klipper will reset the
- When Klipper processes the
EXCLUDE_OBJECT_DEFINEblock, it will update the status with the known objects and pass it on to clients.
- 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.
- If the user requests that an object be cancelled, the client will issue an
EXCLUDE_OBJECT NAME=<name>command to Klipper.
- When Klipper process the command, it will add the object to the list of excluded objects and update the status for the client.
- The client will receive the updated status from Klipper and can use that information to reflect the object's status in the UI.
- 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.
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
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
All available G-Code commands are documented in the G-Code Reference
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=1command is issued.
The list of defined objects is represented in the
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
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.
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.