GCodeWriter: extract MachineKinematics, delete BeltGCodeWriter

BeltGCodeWriter subclassed GCodeWriter and overrode seven methods, five of them
by copying the base body and changing the transform. The base writer already
carried an axis remap and already branched at each of its seven
coordinate-emission decisions; the subclass did the same branching with a
different transform, and the two copies had begun to drift.

Replace the inheritance with a strategy object owned by GCodeWriter:

  CartesianKinematics  to_machine = the existing apply_axis_remap; today's base
                       behaviour, moved rather than changed.
  BeltKinematics       to_machine = MachineFrameTransform o axis_remap o
                       BeltBackTransform, plus a world_coordinates variant for
                       the PA calibration generators.

New: src/libslic3r/GCode/MachineKinematics.{hpp,cpp}, GCode/BeltKinematics.{hpp,cpp}
Deleted: src/libslic3r/BeltGCodeWriter.{hpp,cpp} (341 lines)

Points worth a reviewer's attention:

  * The predicate is must_emit_all_axes(), not couples_axes(). The base returns
    true for any non-identity remap, including pure permutations that do not
    physically couple axes, so the question is "must every axis word be
    emitted", not a statement about kinematics.
  * Every per-site word-omission branch is preserved. The base deliberately
    emits X/Y only, or Z only, or drops Z when its quantised value is unchanged.
    The strategy changes which transform applies, never whether words are
    omitted.
  * set_kinematics() replays the configured remap and build volume onto a newly
    installed strategy, because BeltGCode::init_belt_writer runs before
    GCode.cpp calls set_axis_remap/set_build_volume_max.
  * uses_pointwise_travel_speed() preserves a pre-existing divergence rather
    than introducing one: the base travel_to_xyz emits the raw configured travel
    speed in its final branch, ignoring the first-layer value computed at the
    top, whereas the belt path used the first-layer-aware value throughout. Both
    are kept. Unifying them changes feedrates and belongs in its own change.
  * The [BELT-DEBUG] block is deleted; it rate-limited itself with a
    function-local static thread_local in the hot emission path, and this is the
    commit that would otherwise have moved it into shared code.

This commit is intended to preserve existing export output. That is reviewed by
construction -- each emission site keeps its own omission branch and each policy
divergence is preserved -- and is NOT verified against a G-code diff corpus.
Building that corpus is the outstanding work here.

Two API-equivalence exceptions, neither reachable by any caller today:

  * Belt kinematics with no plane pointer installed, m_is_first_layer true,
    initial and normal travel speeds differing, travel_to_xyz() reaching its
    final branch: the old belt writer selected the initial-layer speed, the new
    writer selects the normal travel speed. The pending-lift and XY-only
    branches keep their previous selection.
  * Belt kinematics installed without set_force_normal_lift(true) and a
    non-normal lift requested: the old belt writer forced a normal lift, the new
    writer can take the slope branch.

The PA-pattern generator reaches the writer through explicit travel_to_z() /
travel_to_xy(), not travel_to_xyz() or the lazy/eager lift paths, and normal
belt export installs both the plane and the forced-normal-lift policy, so
neither exception changes output produced today. They are recorded because a
future caller could reach them.

tests/fff_print/test_gcodewriter.cpp was also not compiling before this branch:
it called writer.to_machine_coords(), a method that existed only on
BeltGCodeWriter. It never surfaced because the build targets OrcaSlicer, not
all, and BUILD_TESTS defaults to OFF, so that translation unit was outside every
compile path. Fixed here; the existing 30-degree coordinate assertions are kept
verbatim as the best available regression net.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011jgzj1sf53KMLPweZ8yeUQ

src/libslic3r/GCode/BeltBackTransform.hpp

@@ -13,7 +13,7 @@ namespace Slic3r {
 // machine's real coordinate space.
 //
 // Initialized once from PrintConfig, then applied per-point in
-// GCodeWriter::to_machine_coords() before axis remapping.
+// BeltKinematics::to_machine() before axis remapping.
 //
 // Active when gcode_back_transform is true AND at least one of:
 //   - a shear axis has global mode enabled, or

src/libslic3r/GCode/BeltKinematics.cpp

@@ -0,0 +1,40 @@
+#include "BeltKinematics.hpp"
+#include "../BeltTransform.hpp"
+#include "../PrintConfig.hpp"
+#include "../GCodeWriter.hpp"
+
+namespace Slic3r {
+
+BeltKinematics::BeltKinematics(const PrintConfig &config, bool world_coordinates)
+    : m_world_coordinates(world_coordinates)
+{
+    m_back_active = m_back_transform.init_from_config(config);
+    m_machine_frame.init_from_config(config);
+    if (m_back_active)
+        // BeltBackTransform stores the inverse of this; keep the forward so
+        // to_logical() can reverse the whole chain.
+        m_back_forward = BeltTransformPipeline::build_forward_transform(config);
+}
+
+Vec3d BeltKinematics::to_machine(const Vec3d &p) const
+{
+    const Vec3d after_back  = m_world_coordinates ? p : m_back_transform.apply(p);
+    const Vec3d after_remap = this->apply_axis_remap(after_back);
+    return m_machine_frame.apply(after_remap);
+}
+
+Vec3d BeltKinematics::to_logical(const Vec3d &machine) const
+{
+    const Vec3d before_frame = m_machine_frame.apply_inverse(machine);
+    const Vec3d before_remap = this->apply_axis_remap_inverse(before_frame);
+    if (m_world_coordinates || ! m_back_active)
+        return before_remap;
+    return m_back_forward * before_remap;
+}
+
+void install_belt_kinematics(GCodeWriter &writer, const PrintConfig &config, bool world_coordinates)
+{
+    writer.set_kinematics(std::make_unique<BeltKinematics>(config, world_coordinates));
+}
+
+} // namespace Slic3r

src/libslic3r/GCode/BeltKinematics.hpp

@@ -0,0 +1,66 @@
+#ifndef slic3r_BeltKinematics_hpp_
+#define slic3r_BeltKinematics_hpp_
+
+#include "MachineKinematics.hpp"
+#include "BeltBackTransform.hpp"
+#include "MachineFrameTransform.hpp"
+
+namespace Slic3r {
+
+class PrintConfig;
+class GCodeWriter;
+
+// Belt-printer machine frame.
+//
+// Forward order, as applied per emitted point:
+//     machine = MachineFrameTransform( axis_remap( BeltBackTransform( logical ) ) )
+//
+// i.e. the slicer->world back-transform runs FIRST and the machine-frame
+// shear/scale LAST, so the latter acts as a global linear transform on the
+// already-placed coordinates.
+//
+// world_coordinates mode (the PA line / PA pattern calibration generators)
+// treats the incoming point as already relative to the belt surface -- X across,
+// Y along the belt, Z above it -- and therefore skips the back-transform while
+// keeping the remap and the machine frame. It is a different coordinate map, not
+// a writer mode, which is why it is fixed at construction.
+class BeltKinematics : public CartesianKinematics
+{
+public:
+    explicit BeltKinematics(const PrintConfig &config, bool world_coordinates = false);
+
+    Vec3d to_machine(const Vec3d &p) const override;
+    Vec3d to_logical(const Vec3d &machine) const override;
+    // Machine -> build-volume frame. Only the machine-frame shear/scale is undone,
+    // matching what GCodeProcessor's bounds validation wants. This is deliberately
+    // NOT to_logical().
+    Vec3d to_build_volume(const Vec3d &machine) const override
+        { return m_machine_frame.apply_inverse(machine); }
+
+    // A belt writer has always emitted full XYZ on every move, whether or not any
+    // individual stage reports itself active. Making this conditional would change
+    // emitted G-code for an identity-transform belt configuration.
+    bool must_emit_all_axes() const override { return true; }
+    bool suppress_lift_at_unknown_position() const override { return true; }
+
+    bool world_coordinates() const { return m_world_coordinates; }
+
+private:
+    BeltBackTransform     m_back_transform;
+    MachineFrameTransform m_machine_frame;
+    // Forward of what m_back_transform inverts, kept so to_logical() can undo it.
+    Transform3d           m_back_forward { Transform3d::Identity() };
+    bool                  m_back_active { false };
+    bool                  m_world_coordinates { false };
+};
+
+// Install a belt machine frame on any GCodeWriter. Any axis remap and build
+// volume already configured on the writer are carried over, so this may be
+// called before or after those setters. Re-calling it with a different
+// world_coordinates value swaps the map (used around the PA line generator).
+void install_belt_kinematics(GCodeWriter &writer, const PrintConfig &config,
+                             bool world_coordinates = false);
+
+} // namespace Slic3r
+
+#endif // slic3r_BeltKinematics_hpp_

src/libslic3r/GCode/GCodeProcessor.cpp

@@ -2774,7 +2774,7 @@ bool GCodeProcessor::check_multi_extruder_gcode_valid(const int
     };
 
     // Belt-printer post-gcode shear/scale/post_remap is applied as the final
-    // step of BeltGCodeWriter::to_machine_coords, so MoveVertex.position is
+    // step of BeltKinematics::to_machine, so MoveVertex.position is
     // in the printer's machine frame.  Undo it here so XY area and Z height
     // checks operate in the build-volume frame that printable_area /
     // printable_height are defined in.  For non-belt printers
@@ -7111,7 +7111,7 @@ void GCodeProcessor::store_move_vertex(EMoveType type, EMovePathType path_type,
     // During the start G-code "prepare" stage the toolhead Z is not yet a real
     // print height on a normal printer, so it is pinned to the first-layer height
     // to keep the preview tidy. Belt printers are the exception: there the Z is
-    // written explicitly by BeltGCodeWriter and the designed-view back-transform
+    // written explicitly by the belt kinematics and the designed-view back-transform
     // couples machine Z into the rendered model Y (the belt tilt mixes the height
     // and belt-feed axes). Overriding Z therefore back-transforms the last
     // prepare-stage move (the unretract before the first extrusion) to model

src/libslic3r/GCode/MachineFrameTransform.hpp

@@ -9,7 +9,7 @@ namespace Slic3r {
 
 // Post-stage machine-frame transform for belt printers.
 //
-// Applied in BeltGCodeWriter::to_machine_coords AFTER the back-transform and
+// Applied in BeltKinematics::to_machine AFTER the back-transform and
 // the gcode_remap_* axis remap.  Maps Cartesian (axis-permuted) G-code
 // coordinates into the printer's physical machine frame.
 //

src/libslic3r/GCode/MachineKinematics.cpp

@@ -0,0 +1,47 @@
+#include "MachineKinematics.hpp"
+
+namespace Slic3r {
+
+// Moved verbatim from GCodeWriter::apply_axis_remap().
+Vec3d CartesianKinematics::apply_axis_remap(const Vec3d &pos) const
+{
+    if (!has_axis_remap())
+        return pos;
+    auto remap = [this, &pos](int r) -> double {
+        int axis = r % 3;
+        if (r < 3) return pos[axis];
+        if (r < 6) return -pos[axis];
+        return m_build_vol_max[axis] - pos[axis];
+    };
+    return { remap(m_remap_x), remap(m_remap_y), remap(m_remap_z) };
+}
+
+// Inverse of the above.  Output axis i is fed by source axis (r_i % 3); walking
+// the three outputs therefore fills every source component exactly once, so long
+// as the remap is a permutation (which set_axis_remap callers guarantee).
+Vec3d CartesianKinematics::apply_axis_remap_inverse(const Vec3d &machine) const
+{
+    if (!has_axis_remap())
+        return machine;
+    Vec3d out = Vec3d::Zero();
+    const int r[3] = { m_remap_x, m_remap_y, m_remap_z };
+    for (int i = 0; i < 3; ++i) {
+        const int axis = r[i] % 3;
+        if (r[i] < 3)      out[axis] = machine[i];
+        else if (r[i] < 6) out[axis] = -machine[i];
+        else               out[axis] = m_build_vol_max[axis] - machine[i];
+    }
+    return out;
+}
+
+Vec3d CartesianKinematics::to_machine(const Vec3d &p) const
+{
+    return this->apply_axis_remap(p);
+}
+
+Vec3d CartesianKinematics::to_logical(const Vec3d &machine) const
+{
+    return this->apply_axis_remap_inverse(machine);
+}
+
+} // namespace Slic3r

src/libslic3r/GCode/MachineKinematics.hpp

@@ -0,0 +1,95 @@
+#ifndef slic3r_MachineKinematics_hpp_
+#define slic3r_MachineKinematics_hpp_
+
+#include "../Point.hpp"
+
+namespace Slic3r {
+
+// The frame contract for emitted movement.
+//
+// GCodeWriter produces points in the *logical placed* frame: plate offsets have
+// already been subtracted, but no machine-specific mapping has been applied.
+// A MachineKinematics turns that into the coordinates actually written to
+// G-code, and answers the two structural questions the writer needs in order to
+// decide which axis words it may omit.
+//
+// This is a seam for writer-generated movement only.  Start/end/custom G-code,
+// classic wipe-tower output and GCodeWriter::extrude_arc_to_xy() do NOT pass
+// through it; see doc in 09-orca-machinekinematics-split-plan.md section 6.
+class MachineKinematics
+{
+public:
+    virtual ~MachineKinematics() = default;
+
+    // Logical placed point -> emitted machine point.
+    virtual Vec3d to_machine(const Vec3d &p) const = 0;
+
+    // Inverse of to_machine(), back to the logical placed frame.  Intended for
+    // consumers that must reconstruct model coordinates from emitted G-code
+    // (the G-code viewer's upright preview).
+    virtual Vec3d to_logical(const Vec3d &machine) const = 0;
+
+    // Machine point -> build-volume frame, for bounds validation only.  This is
+    // deliberately NOT to_logical(): the build-volume check wants the physical
+    // frame the printable area is expressed in, not the model frame.  Keeping
+    // them separate stops the two contracts from being confused.
+    virtual Vec3d to_build_volume(const Vec3d &machine) const = 0;
+
+    // True when a move must emit X, Y and Z because omitting a word would be
+    // wrong under this mapping.  Deliberately not called "couples_axes": a pure
+    // axis permutation forces full emission without physically coupling axes.
+    virtual bool must_emit_all_axes() const = 0;
+
+    // True when a separate in-place lift must be suppressed while the current
+    // position is unknown, because _travel_to_z() re-emits the logical X/Y
+    // through this mapping and an uninitialised position would map to a bogus
+    // machine point.
+    virtual bool suppress_lift_at_unknown_position() const = 0;
+
+    // Configuration.  GCodeWriter forwards its setters here so that the state
+    // lives with the strategy and a strategy installed before the setters run
+    // still receives it.
+    virtual void set_axis_remap(int rx, int ry, int rz) = 0;
+    virtual void set_build_volume_max(const Vec3d &max) = 0;
+};
+
+// Axis remap only -- the historical GCodeWriter behaviour, moved verbatim.
+//
+// The remap encodes, per output axis, which source axis feeds it and how:
+//   r < 3 : source axis r, unchanged
+//   r < 6 : source axis r-3, negated
+//   else  : source axis r-6, reversed within the build volume
+class CartesianKinematics : public MachineKinematics
+{
+public:
+    Vec3d to_machine(const Vec3d &p) const override;
+    Vec3d to_logical(const Vec3d &machine) const override;
+    Vec3d to_build_volume(const Vec3d &machine) const override { return machine; }
+
+    bool must_emit_all_axes() const override { return this->has_axis_remap(); }
+    // The base writer has never suppressed the lift, not even under a remap that
+    // makes _travel_to_z re-emit X/Y.  That is arguably a latent bug, but fixing
+    // it here would change emitted G-code, so today's behaviour is preserved and
+    // the divergence from BeltKinematics is deliberate.
+    bool suppress_lift_at_unknown_position() const override { return false; }
+
+    void set_axis_remap(int rx, int ry, int rz) override
+        { m_remap_x = rx; m_remap_y = ry; m_remap_z = rz; }
+    void set_build_volume_max(const Vec3d &max) override { m_build_vol_max = max; }
+
+    bool has_axis_remap() const
+        { return m_remap_x != 0 || m_remap_y != 1 || m_remap_z != 2; }
+
+protected:
+    Vec3d apply_axis_remap(const Vec3d &pos) const;
+    Vec3d apply_axis_remap_inverse(const Vec3d &pos) const;
+
+    int   m_remap_x { 0 };
+    int   m_remap_y { 1 };
+    int   m_remap_z { 2 };
+    Vec3d m_build_vol_max { Vec3d::Zero() };
+};
+
+} // namespace Slic3r
+
+#endif // slic3r_MachineKinematics_hpp_