GCodePlotter_CommandSheet.txt

================================================================================
  GCodePlotter — Command Reference
  Processing 4.x Library for Bambu Lab A1 Mini Pen Plotter
================================================================================

Config file location:
  ~/Documents/Processing/libraries/GCodePlotter/Config/gcodeplotter.config

GCode files (optional, auto-loaded if present):
  ~/Documents/Processing/libraries/GCodePlotter/Config/StartGCode.txt
  ~/Documents/Processing/libraries/GCodePlotter/Config/EndGCode.txt

Find & Replace regex (to convert existing sketches):
  Search:  \b(line|rect|ellipse|bezier|curve|beginShape|endShape|vertex|bezierVertex|curveVertex|pushMatrix|popMatrix|translate|rotate|scale)\(
  Replace: plotter.$1(

────────────────────────────────────────────────────────────────────────────────
  CONSTRUCTOR
────────────────────────────────────────────────────────────────────────────────

  new GCodePlotter(this)
    Load all settings from config file.

  new GCodePlotter(this, buildWidthMm, buildHeightMm)
    Load settings from config, but override build volume with given values.
    Example: new GCodePlotter(this, 180, 180)

────────────────────────────────────────────────────────────────────────────────
  CONFIGURATION  (override config file values for the current sketch)
────────────────────────────────────────────────────────────────────────────────

  PRINTER
  plotter.setYDeadzone(mm)          Unusable zone at the rear of the bed (mm).
                                    Center Y is calculated as (buildHeight + yDeadzone) / 2.
                                    Example: plotter.setYDeadzone(32)

  OUTPUT SIZE & POSITION
  plotter.setOutputSize(w, h)       Set drawing size on the bed in mm.
                                    The center of the drawing always stays at the
                                    bed center — independent of this size.
                                    Example: plotter.setOutputSize(140, 140)

  plotter.setOriginOffset(x, y)     Shift the drawing from the bed center by x/y mm.
                                    Default (0, 0) = perfectly centered.
                                    Example: plotter.setOriginOffset(10, 0)

  plotter.setFlipY(bool)            Flip the Y axis. true = sketch-top maps to
                                    printer-front (large Y). Default: false.

  PEN
  plotter.setZOffsetMm(mm)          Z offset of pen holder (mm). Applied via
                                    G1 Z{value} before G92 Z0. Calibrate this
                                    for your specific pen holder!
                                    Example: plotter.setZOffsetMm(17.0)

  plotter.setPenDownZ(z)            Z height when the pen is drawing. Default: 0.0
  plotter.setPenUpZ(z)              Z height when the pen is traveling. Default: 3.0
  plotter.setPauseZ(z)              Z height during a pause (pen change). Default: 20.0

  FEED RATES (mm/min)
  plotter.setDrawFeedRate(f)        Speed while drawing. Default: 3000
  plotter.setTravelFeedRate(f)      Speed while traveling (pen up). Default: 18000
  plotter.setZFeedRate(f)           Speed for Z moves. Default: 900

  E VALUE
  plotter.setUseEValue(bool)        Enable/disable E value in G1 lines.
                                    Recommended true for Bambu Lab firmware.
  plotter.setEValuePerMm(e)         E increment per mm of travel. Default: 0.0001

  CURVES
  plotter.setCurveDetail(n)         Number of segments per curve/ellipse. Default: 30
                                    Higher = smoother, more GCode lines.

  CUSTOM GCODE
  plotter.setStartGCode(string)     Override start GCode with a string.
  plotter.setEndGCode(string)       Override end GCode with a string.
  plotter.setStartGCodeFromFile(path)  Load start GCode from a .txt file.
                                       Example: plotter.setStartGCodeFromFile(sketchPath("start.txt"))
  plotter.setEndGCodeFromFile(path)    Load end GCode from a .txt file.

────────────────────────────────────────────────────────────────────────────────
  RECORDING
────────────────────────────────────────────────────────────────────────────────

  plotter.beginRecord()             Start recording. Clears all previous paths.
                                    Call this before your drawing commands.

  plotter.endRecord("filename")     Stop recording and save filename.gcode
                                    and filename.svg to the sketch folder.

  plotter.saveGCode("file.gcode")   Save GCode only (no SVG).
  plotter.saveSVG("file.svg")       Save SVG only (no GCode).

  plotter.pause()               Insert a user-input pause (M400 U1).
                                Z lifts to pauseZ, printer waits until
                                user presses resume on the touchscreen
                                or in Bambu Studio. Z returns to penUpZ.
                                Example:
                                  plotter.ellipse(300, 300, 400, 400); // pen 1
                                  plotter.pause();     // wait for user
                                  plotter.ellipse(300, 300, 200, 200); // pen 2

  plotter.pause(seconds)        Insert a timed pause (M400 S{t}).
                                Z lifts to pauseZ, printer waits for the
                                given number of seconds, then continues.
                                No user interaction needed.
                                Example:
                                  plotter.pause(30);   // wait 30 seconds

────────────────────────────────────────────────────────────────────────────────
  DRAWING COMMANDS
  Call these instead of Processing's built-in versions.
  They draw to the screen AND record the path for GCode export.
────────────────────────────────────────────────────────────────────────────────

  PRIMITIVES
  plotter.line(x1, y1, x2, y2)     Draw a straight line.

  plotter.rect(x, y, w, h)         Draw a rectangle (4 sides, closed path).
                                    x/y = top-left corner, w/h = width/height.

  plotter.ellipse(cx, cy, w, h)    Draw an ellipse or circle (discretized).
                                    cx/cy = center, w/h = width/height.

  BEZIER & SPLINES
  plotter.bezier(x1,y1, cx1,cy1, cx2,cy2, x2,y2)
                                    Draw a cubic Bezier curve.
                                    (x1,y1) = start, (cx1,cy1)+(cx2,cy2) = control points,
                                    (x2,y2) = end.

  plotter.curve(x1,y1, x2,y2, x3,y3, x4,y4)
                                    Draw a Catmull-Rom spline segment.
                                    Curve runs from (x2,y2) to (x3,y3).
                                    (x1,y1) and (x4,y4) are outer control points.

  SHAPES
  plotter.beginShape()              Start a shape (polygon mode).
  plotter.beginShape(mode)          Start a shape with a Processing mode constant.

  plotter.vertex(x, y)             Add a straight vertex to the current shape.

  plotter.bezierVertex(cx1,cy1, cx2,cy2, x,y)
                                    Add a Bezier vertex. Needs a preceding vertex()
                                    as anchor point.

  plotter.curveVertex(x, y)        Add a Catmull-Rom spline vertex.
                                    Minimum 4 consecutive curveVertex calls
                                    for a smooth curve. First and last are
                                    outer control points (not drawn).

  plotter.endShape()               Close and finalize the shape (open path).
  plotter.endShape(CLOSE)          Close and finalize the shape (closed path,
                                    last point connects back to first).

────────────────────────────────────────────────────────────────────────────────
  TRANSFORMS
  Mirror these calls alongside Processing's own transform calls.
  Processing transforms affect the screen preview.
  Plotter transforms affect the recorded GCode coordinates.
────────────────────────────────────────────────────────────────────────────────

  plotter.pushMatrix()              Save current transform to stack.
  plotter.popMatrix()               Restore previous transform from stack.

  plotter.translate(dx, dy)        Shift origin by (dx, dy) in pixels.
  plotter.rotate(angle)            Rotate around current origin (radians).
                                    Example: plotter.rotate(PI / 4)  // 45 degrees
  plotter.scale(s)                 Scale uniformly.
  plotter.scale(sx, sy)            Scale separately in X and Y.
  plotter.resetMatrix()            Reset all transforms (like resetMatrix() in Processing).

  USAGE PATTERN:
    pushMatrix();              plotter.pushMatrix();
    translate(cx, cy);         plotter.translate(cx, cy);
    rotate(angle);             plotter.rotate(angle);
    rect(-w/2, -h/2, w, h);    plotter.rect(-w/2, -h/2, w, h);
    popMatrix();               plotter.popMatrix();

────────────────────────────────────────────────────────────────────────────────
  INFO & DEBUGGING
────────────────────────────────────────────────────────────────────────────────

  plotter.getPathCount()           Returns number of recorded paths (int).
  plotter.getBuildWidth()          Returns build volume width in mm (float).
  plotter.getBuildHeight()         Returns build volume height in mm (float).
  plotter.printConfigPath()        Prints the active config file path to console.

────────────────────────────────────────────────────────────────────────────────
  CONSOLE WARNINGS
────────────────────────────────────────────────────────────────────────────────

  The library prints a warning once per export if any point falls outside
  the bed boundaries:

  GCodePlotter WARNING: X < 0              Point is left of the bed.
  GCodePlotter WARNING: X > {buildWidth}   Point is right of the bed.
  GCodePlotter WARNING: Y < yDeadzone      Point is inside the rear deadzone.
  GCodePlotter WARNING: Y > {buildHeight}  Point is beyond the front of the bed.

  If you see these, reduce your output size or adjust the origin offset.

────────────────────────────────────────────────────────────────────────────────
  MINIMAL SKETCH TEMPLATE
────────────────────────────────────────────────────────────────────────────────

  import gcodeplotter.*;
  GCodePlotter plotter;

  void setup() {
    size(600, 600);
    plotter = new GCodePlotter(this);  // all values from config
    draw_everything();
  }

  void draw() {}

  void draw_everything() {
    background(255);
    stroke(0); noFill();
    plotter.ellipse(300, 300, 500, 500);
    plotter.rect(50, 50, 500, 500);
  }

  void keyPressed() {
    if (key == 's') {
      plotter.beginRecord();
      draw_everything();
      plotter.endRecord("output");
    }
  }

================================================================================