docs: update analysis and metadata docs

Signed-off-by: Eric Callahan
Arksine · Feb 16, 2025 · c2e3e20 · c2e3e20
1 parent 313fd77
commit c2e3e20
Show file tree

Hide file tree

Showing 4 changed files with 98 additions and 13 deletions.
diff --git a/docs/configuration.md b/docs/configuration.md
@@ -547,11 +547,11 @@ estimator_timeout: 600
 #   is given to process a gcode file before processing is
 #   aborted.  The default is 600 seconds.
 enable_auto_analysis: false
-#   When set to true Klipper Estimator will be used to perform a time
-#   analysis for gcode files immediately after metadata is processed.
-#   The "total_time" result will replace the existing "estimated_time"
-#   field in the gcode metadata.  This automates the time analysis for
-#   any event that triggers metadata processing.   Default is false.
+#   When set to true Klipper Estimator will be used to perform a
+#   post-process on gcode files immediately prior to metadata extraction.
+#   The post-process will update the time estimate and M73 commands present
+#   in the gcode file.  This automates the time analysis for any event
+#   that triggers metadata processing.   Default is false.
 enable_estimator_updates: false
 #   When true Moonraker will create and register an entry for
 #   klipper_estimator with the update manager.  Default is false.

diff --git a/docs/external_api/file_manager.md b/docs/external_api/file_manager.md
@@ -214,6 +214,7 @@ GET /server/files/metadata?filename=tools/drill.gcode
     "size": 1629418,
     "modified": 1706359465.4947228,
     "uuid": "473a41d2-15f4-434b-aeb4-ab96eb122bbf",
+    "file processors": [],
     "slicer": "PrusaSlicer",
     "slicer_version": "2.7.1+win64",
     "gcode_start_byte": 87410,
@@ -259,6 +260,9 @@ GET /server/files/metadata?filename=tools/drill.gcode
 | `size`                  |   int    | The gcode file size in bytes.                                |
 | `modified`              |  float   | The last modified time in Unix Time (seconds).               |
 | `uuid`                  |  string  | A unique identifier for the metadata object.                 |
+| `file_processors`       | [string] | An array of `File Processors` that have performed processed  |
+|                         |          | and modified the file.                                       |^
+|                         |          | #file-processor-app-desc                                     |+
 | `slicer`                |  string  | The name of the slicer software used to slice the file.      |
 | `slicer_version`        |  string  | The version of the slicer software.                          |
 | `gcode_start_byte`      |   int    | The byte offset in the file where the first gcode command    |
@@ -294,6 +298,15 @@ GET /server/files/metadata?filename=tools/drill.gcode
 | `relative_path` | string | The path of the thumbnail, relative to the gcode file's parent. |
 { #thumbnail-info-spec } Thumbnail Info
 
+| Application               | Description                                                      |
+| ------------------------- | ---------------------------------------------------------------- |
+| `preprocess_cancellation` | Converts "object identifiers" generated by the slicer into       |
+|                           | GCode commands for use with Klipper's `[exclude_object]` module. |^
+| `klipper_estimator`       | Performs a time analysis on the gcode file, replacing the        |
+|                           | time estimates in the file with the result.  Also updates M73    |^
+|                           | commands.                                                        |^
+{ #file-processor-app-desc } File Processors
+
 //// Note
 Metadata field availability depends on the Slicer application and its
 configuration.  If a field cannot be parsed from the slicer it will

diff --git a/docs/external_api/integrations.md b/docs/external_api/integrations.md
@@ -576,8 +576,7 @@ Content-Type: application/json
 
 {
     "filename": "my_file.gcode",
-    "estimator_config": "custom_estimator_cfg.json",
-    "update_metadata": false
+    "estimator_config": "custom_estimator_cfg.json"
 }
 ```
 
@@ -587,8 +586,7 @@ Content-Type: application/json
     "method": "server.analysis.estimate",
     "params": {
         "filename": "my_file.gcode",
-        "estimator_config": "custom_estimator_cfg.json",
-        "update_metadata": false
+        "estimator_config": "custom_estimator_cfg.json"
     }
     "id": 4654
 }
@@ -609,10 +607,6 @@ Content-Type: application/json
 |                    |        |                    | in the `[analysis]` section of            |^
 |                    |        |                    | `moonraker.conf` or the default dumped    |^
 |                    |        |                    | config will be used.                      |^
-| `update_metadata`  |  bool  | false              | When set to `true` the `estimated_time`   |
-|                    |        |                    | field of the gcode file's metadata will   |^
-|                    |        |                    | be overwritten with the `total_time`      |^
-|                    |        |                    | result from Klipper Estimator.            |^
 
 ///
 
@@ -1251,6 +1245,83 @@ All time estimates are reported in seconds.
 
 ///
 
+### Post process a file
+
+Klipper Estimator will perform a time analysis and use the results to
+modify the time estimates in the file.  If M73 (progress) commands are
+present they will also be modified.
+
+```{.http .apirequest title="HTTP Request"}
+POST /server/analysis/process
+Content-Type: application/json
+
+{
+    "filename": "my_file.gcode",
+    "estimator_config": "custom_estimator_cfg.json",
+    "force": false
+}
+```
+
+```{.json .apirequest title="JSON-RPC Request"}
+{
+    "jsonrpc": "2.0",
+    "method": "server.analysis.process",
+    "params": {
+        "filename": "my_file.gcode",
+        "estimator_config": "custom_estimator_cfg.json",
+        "force": false
+    }
+    "id": 4654
+}
+```
+
+/// api-parameters
+    open: True
+
+| Name               |  Type  | Default            | Description                                    |
+| ------------------ | :----: | ------------------ | ---------------------------------------------- |
+| `filename`         | string | **REQUIRED**       | The path to the gcode file to post-process.    |
+|                    |        |                    | This should be a path relative to the `gcodes` |^
+|                    |        |                    | root folder.                                   |^
+| `estimator_config` | string | **CONFIG_DEFAULT** | The path to a Klipper Estimator config         |
+|                    |        |                    | file, relative to the `config` root            |^
+|                    |        |                    | folder.  When omitted the file configured      |^
+|                    |        |                    | in the `[analysis]` section of                 |^
+|                    |        |                    | `moonraker.conf` or the default dumped         |^
+|                    |        |                    | config will be used.                           |^
+| `force`            |  bool  | false              | By default the request will not perform a new  |
+|                    |        |                    | post-process if the file was already processed |^
+|                    |        |                    | by Klipper Estimator. When `force` is `true`   |^
+|                    |        |                    | the file will be post-processed regardless.    |^
+
+///
+
+```{.json .apiresponse title="Example Response"}
+{
+    "prev_processed": false,
+    "version": "v3.7.3",
+    "bypassed": false
+}
+```
+
+/// api-response-spec
+    open: True
+
+| Field            | Type | Description                                                |
+| ---------------- | :--: | ---------------------------------------------------------- |
+| `prev_processed` | bool | Will be `true` if the requested file was previously        |
+|                  |      | processed by Klipper Estimator.                            |^
+| `version`        | str  | The version of Klipper Estimator used to process the file. |
+| `bypassed`       | bool | Will be `true` if the post-processing was bypassed.  This  |
+|                  |      | occurs if the file was previously processed by Klipper     |^
+|                  |      | Estimator and the `force` argument is `false`.             |^
+
+///
+
+/// note
+If the `file_manager` has `inotify` enabled the post-process will trigger a
+`create_file` event, which will in turn trigger metadata extraction.
+///
 
 ### Dump the current configuration
 

diff --git a/docs/external_api/jsonrpc_notifications.md b/docs/external_api/jsonrpc_notifications.md
@@ -580,6 +580,7 @@ notify_history_changed
                     "size": 538254,
                     "modified": 1646770808,
                     "uuid": "4022d6bd-e5f5-45d7-84af-f38bcc57a5d3",
+                    "file processors": [],
                     "slicer": "PrusaSlicer",
                     "slicer_version": "2.4.0+linux-x64-GTK3",
                     "gcode_start_byte": 51238,