100 lines
5.4 KiB
Markdown
100 lines
5.4 KiB
Markdown
# 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](Config_Reference.md#exclude_object) (also see the [command
|
|
reference](G-Codes.md#exclude-object) and
|
|
[sample-macros.cfg](../config/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](Status_Reference.md#exclude_object).
|
|
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](https://github.com/kageurufu/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](./G-Codes.md#excludeobject)
|
|
|
|
## Status Information
|
|
The state of this module is provided to clients by the [exclude_object
|
|
status](Status_Reference.md#exclude_object).
|
|
|
|
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.
|