docs: add exclude_object documentation

Also include sample macros to add M486 compatibility.

Signed-off-by: Franklyn Tackitt <git@frank.af>
Co-authored-by: Troy Jacobson <troy.d.jacobson@gmail.com>

1 files changed, 99 insertions, 0 deletions

diff --git a/docs/Exclude_Object.md b/docs/Exclude_Object.md
new file mode 100644
index 00000000..d2681489
--- /dev/null
+++ b/docs/Exclude_Object.md
@@ -0,0 +1,99 @@
+# Exclude Obects
+
+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.