docs: Suggested improvements to Input Shaper tuning guide

Signed-off-by: Dmitry Butyugin <dmbutyugin@google.com>

docs/Config_checks.md

@@ -162,6 +162,6 @@ consider calibrating [pressure advance](Pressure_Advance.md).
 It may be necessary to perform other types of detailed printer
 calibration - a number of guides are available online to help with
 this (for example, do a web search for "3d printer calibration").
-As an example, if you experience the effect called ghosting or ringing,
+As an example, if you experience the effect called ringing,
-you may try following [ghosting compensation](Ghosting_Compensation.md)
+you may try following [resonance compensation](Resonance_Compensation.md)
 tuning guide.

docs/Overview.md

@@ -38,6 +38,8 @@ communication with the Klipper developers.
   sensorless homing.
 - [Skew correction](skew_correction.md): Adjustments for axes not
   perfectly square.
+- [Resonance compensation](Resonance_Compensation.md): Reduce ringing in prints
+  by measuring printer resonances and configuring the input shaping.
 - [G-Codes](G-Codes.md): Information on commands supported by Klipper.
 
 # Developer Documentation

docs/Resonance_Compensation.md

@@ -1,9 +1,18 @@
-Ghosting Compensation
+Resonance Compensation
 ====================
 
-Klipper supports Input Shaping - a technique that can be used to reduce ghosting
+Klipper supports Input Shaping - a technique that can be used to reduce ringing
-in prints. [Input shaping](https://en.wikipedia.org/wiki/Input_shaping) is an
+(also known as echoing, ghosting or rippling) in prints. Ringing is a surface
-open-loop control technique which creates a commanding signal that cancels its
+printing defect when, typically, elements like edges repeat themselves on a
+printed surface as a subtle 'echo':
+
+|![Ringing test](img/ringing-test.jpg) |![3D Benchy](img/ringing-3dbenchy.jpg) |
+|:--:|:--:|
+
+Ringing is caused by mechanical vibrations in the printer due to quick changes
+of the printing direction.
+[Input shaping](https://en.wikipedia.org/wiki/Input_shaping) is an open-loop
+control technique which creates a commanding signal that cancels its
 own vibrations.
 
 **Warning**: Input Shaping support is experimental. You should consider using it
@@ -11,7 +20,7 @@ only if you already have ghosting and ringing in prints, otherwise it is not
 advised to enable it. Input shaping requires some tuning and measurements
 before it can be enabled.
 
-Note that ghosting usually has mechanical origins: insufficiently rigid printer
+Note that ringing usually has mechanical origins: insufficiently rigid printer
 frame, non-tight or too springy belts, alignment issues of mechanical parts,
 heavy moving mass, etc. Those should be checked and fixed first.
 
@@ -36,7 +45,9 @@ Slice the ringing test model, which can be found in
 First, measure the **ringing frequency**.
 
 1. Increase `max_accel` and `max_accel_to_decel` parameters in your
-   `printer.cfg` to 7000.
+   `printer.cfg` to 7000. Note that this is only needed for tuning, and more
+   proper value will be selected in the corresponding
+   [section](#selecting-max_accel).
 2. Restart the firmware: `RESTART`.
 3. Disable Pressure Advance: `SET_PRESSURE_ADVANCE ADVANCE=0`.
 4. If you have already added `[input_shaper]` section to the printer.cfg,
@@ -192,16 +203,36 @@ max_accel should be chosen such as to prevent that. Another parameter that can
 impact smoothing is square_corner_velocity, so it is not advisable to increase
 it above the default 5 mm/sec to prevent increased smoothing.
 
-Inspect the model for the chosen input shaper. Take a note at which
+In order to select a suitable max_accel value, inspect the model for the chosen
-acceleration:
+input shaper. First, take a note at which acceleration ringing is still small -
+that you are comfortable with it.
 
-  * ringing is still small - that you are comfortable with it;
+Next, check the smoothing. To help with that, the test model has a small gap
-  * corners of the test model still show 'bulges' from disabled pressure
+in the wall (0.15 mm):
-    advance - remember that **input shaping is not a replacement of PA**.
+
+![Test gap](img/smoothing-test.png)
+
+As the acceleration increases, so does the smoothing, and the actual gap
+widens:
+
+![Shaper smoothing](img/shaper-smoothing.jpg)
+
+In this picture, the acceleration increases left to right, and the gap starts
+to grow starting from 3500 mm/sec^2 (5-th band from the left). So the good
+value for max_accel = 3000 (mm/sec^2) in this case to avoid the excessive
+smoothing.
+
+Note the acceleration when the gap is still very small in your test print.
+If you see bulges, but no gap in the wall at all, even at high accelerations,
+it may be due to disabled Pressure Advance, especially on Bowden extruders.
+If that is the case, you may need to repeat the print with the PA enabled.
+It may also be a result of a miscalibrated (too high) filament flow, so it is
+a good idea to check that too.
+
+Choose the minimum out of the two acceleration values (from ringing and
+smoothing), and put it as max_accel into printer.cfg (you can delete
+max_accel_or_decel or revert it to the old value).
 
-Choose the minimum out of the two acceleration values, and put it as max_accel
-into printer.cfg (you can delete max_accel_or_decel or revert it to the old
-value).
 
 As a note, it may happen - especially at low ringing frequencies - that EI
 shaper will cause too much smoothing even at lower accelerations. In this case,
@@ -269,6 +300,9 @@ After both new `shaper_freq_x` and `shaper_freq_y` parameters have been
 calculated, you can update `[input_shaper]` section in `printer.cfg` with the
 new `shaper_freq_x` and `shaper_freq_y` values.
 
+Do not forget to revert the changes to `max_accel` and `max_accel_to_decel`
+parameters in the `printer.cfg` after finishing this section.
+
 ## Pressure Advance
 
 If you use Pressure Advance, it may need to be re-tuned. Follow the
@@ -355,7 +389,7 @@ Troubleshooting and FAQ
 ### I cannot get reliable measurements of resonance frequencies
 
 First, make sure it is not some other problem with the printer instead of
-ghosting. If the measurements are not reliable because, say, the distance
+ringing. If the measurements are not reliable because, say, the distance
 between the oscillations is not stable, it might mean that the printer has
 several resonance frequencies on the same axis. One may try to follow the
 tuning process described in
@@ -370,7 +404,7 @@ increase square_corner_velocity parameters. It might also be better to choose
 MZV or even ZV input shapers over EI (or 2HUMP_EI and 3HUMP_EI shapers).
 
 
-### After successfully printing for some time without ghosting, it appears to come back
+### After successfully printing for some time without ringing, it appears to come back
 
 It is possible that after some time the resonance frequencies have changed.
 E.g. maybe the belts tension has changed (belts got more loose), etc. It is a
@@ -393,6 +427,12 @@ SET_INPUT_SHAPER SHAPER_FREQ_X=... SHAPER_FREQ_Y=...
 
 And similarly when switching back to carriage 0.
 
+### Does input_shaper affect print time?
+
+No, `input_shaper` feature has pretty much no impact on the print times by
+itself. However, the value of `max_accel` certainly does (tuning of this
+parameter described in [this section](#selecting-max_accel)).
+
 
 Technical details
 =================