LEAFMINER 0.1.2
===============

Grasshopper control for any pen plotter axicli can drive - machines built on
the EiBotBoard (EBB) controller, such as the AxiDraw and the UUNA TEK iDraw
H SE - in Rhino 8 for Windows.

Leafminer turns Rhino curves and text into pen plots without leaving
Grasshopper: preview the toolpath, estimate the time, plot, pause for pen
changes and resume, all from buttons on the canvas. It drives the plotter
through axicli, the AxiDraw command-line tool from Evil Mad Scientist.

Leafminer is an independent project. It is not made by, or affiliated with,
Evil Mad Scientist Laboratories or UUNA TEK.


CONTENTS
--------

  1. Requirements
  2. Installing axicli (once)
  3. Before your first plot (safety)
  4. Quick start
  5. The components
  6. Pens: pen_profiles.json and layer names
  7. Where Leafminer keeps its files
  8. Troubleshooting
  9. Licence


1. REQUIREMENTS
---------------

- Rhino 8 for Windows (Rhino 7 and Mac are not supported).
- A pen plotter with an EBB (EiBotBoard) controller that axicli can drive,
  connected by USB. Leafminer picks the A4 or A3 travel from the bed size you
  set, so beds up to 430 x 297 mm work; larger beds are refused for now.
  GRBL-based plotters are not supported.
- An internet connection once, to install axicli.


2. INSTALLING AXICLI (do this once)
-----------------------------------

axicli runs on the Python that comes with Rhino 8, so you don't need to
install Python yourself - only axicli, from inside Grasshopper:

  1. Open the example definition (or place the Leafminer components). Until
     axicli is installed, the Plotter's msg says "AXICLI NOT INSTALLED".
  2. Press the "Install axicli" button next to the Setup component (internet
     needed). It downloads axicli and installs it into
     %APPDATA%\Leafminer\axicli-py39 in the background; msg and the Report
     show the progress, then "axicli installed ..." with its version.
  3. The Plotter's Report now shows
       Runs on  : Rhino 8's Python, axicli in ...

If msg says Rhino's Python was not found: open the Script Editor (type
ScriptEditor in Rhino), run an empty Python 3 script once so Rhino sets up
its own Python (in %USERPROFILE%\.rhinocode\py39-rh8), and press the button
again.

To update axicli later, press "Install axicli" again.
To uninstall it, delete the folder %APPDATA%\Leafminer\axicli-py39.
Rhino's own files are not changed.

If the button doesn't work (e.g. a firewall), use "Install axicli.bat"
instead - the manual fallback, which does the same install in a window:
double-click it. If Windows warns about the file ("Windows protected your
PC"), click "More info", then "Run anyway". You can read what it does first:
right-click it and choose Edit - nothing in it runs until you double-click
it. The same file also explains how to install axicli by hand in a Command
Prompt (the MANUAL INSTALL steps at its top).

Already have axicli in another Python? Put its command in the Setup component's
Cmd input (e.g. the full path to axicli.exe) and skip this step. Until axicli
is installed for Rhino's Python, Leafminer also uses an axicli found on PATH.


3. BEFORE YOUR FIRST PLOT (SAFETY)
----------------------------------

Leafminer moves real hardware. Please:

- Press Estimate before Plot. It writes the plot file and previews it
  offline (time, layers, DrawPaths / TravelPaths in the viewport) - nothing
  moves. Check the preview sits on the bed where you expect.
- Set zero by hand: with the motors off, move the carriage to the top-left
  corner of the bed, then press MotorsOn. Every plot, Home and Go To is
  measured from there. Leafminer can't read the carriage position; it keeps
  track of it, so if you move the carriage by hand, press MotorsOff and
  MotorsOn again.
- Find your pen heights on scrap paper first: Lower and Raise use the Pen
  component's PenDown and PenUp (0-100 %, lower number = lower pen).
- Start small and slow. The speeds default to axicli's own (DrawSpeed 25,
  MoveSpeed 75); lower them on the Speed component if in doubt.
- Use Boundary to dot the corners of the plot before you commit to it.
- Stop pauses a plot (progress is kept) and returns to zero; Resume carries
  on. Keep a hand near the plotter's power during your first plots.


4. QUICK START
--------------

  1. Open the example definition. Wire your curves (or text) into the
     Plotter's Geometry input. Use Rhino object IDs - referenced geometry or
     Grasshopper's Geometry Pipeline - so Leafminer can read layers and skip
     hidden or locked objects.
  2. Pick your bed size on the Bed Size component (a name like A3, a size
     like '300 x 200', or a rectangle drawn in Rhino) and wire it to
     BedSize.
  3. Press Estimate and read the Report: time, layers, pen order, pauses.
  4. Set zero (see above), find your pen heights, then press Plot.
  5. To plot with several pens, name the Rhino layers after them (section 6).
     Leafminer pauses at every pen change and returns to zero; swap the pen
     and press Resume.

The Plotter turns red with an error you can hover when it can't work, and
orange with a warning when something is worth a look. Hover any input for
its help: optional inputs start with "(Optional)" and say what happens when
they aren't connected.


5. THE COMPONENTS
-----------------

Plotter (the main component). Required inputs: Control, Geometry, BedSize.
  Optional: PauseAt (Rhino layer numbers to pause before, as listed in the
  Report), DrawTravelPaths, and the group inputs below.
  Outputs: State, Report, msg, DrawPaths, TravelPaths, Pens.

Bed Size - the bed rectangle, from a size name, 'W x H' in mm, a point or
  a rectangle drawn in Rhino.

Group components - each bundles a few buttons or settings into one wire.
Only Control is required; an unwired group uses its defaults.
  Control        Estimate, Plot, Stop, Resume, Home
  Motors         MotorsOn (sets zero here), MotorsOff
  Boundary       Boundary (dot the plot's corners), BoundaryOffset
  Pen            Raise, Lower, PenUp, PenDown, PenDownOffset
  Plot Settings  ConstSpeed, Reorder, KeepLayers, GroupByPen
  Pen Stepdown   StepOn, PenStep, StepDist (lower a wearing tip as it goes)
  Speed          MoveSpeed, DrawSpeed, Accel, LowerRate, RaiseRate
  Text           TextFill, TextFillStyle, PenSize, FillAdjust, FillAngle
  Go To          GoTo, Target (an MD Slider across the bed, or a point)
  Setup          Folder, Name, PenFile, Cmd, Install axicli


6. PENS: PEN_PROFILES.JSON AND LAYER NAMES
------------------------------------------

Name a Rhino layer after its pen and Leafminer uses that pen's settings:

    Layer Name | Pen type | Color          e.g.  Outlines | Muji Gel 0.5 | Red

Sub-layers take their parent's pen. "Fill | | Black" keeps the parent's pen
type and changes only the colour. Case and extra spaces don't matter.
Layers with no pen in their name plot with no offset.

The pen types come from the pen list, %APPDATA%\Leafminer\pen_profiles.json.
The first time Leafminer runs it writes the starter list there (so does
"Install axicli.bat"); after that the file is never overwritten, so edit it
there. To use another file, put its path in the Setup component's PenFile
input. The Plotter's Pens output lists every pen, its colours and the layer
name that picks it, plus any problems in the file.

Each entry in "families" is one pen body and tip size:

    {
      "name": "Pigma Micron 005",      the Pen type in layer names
      "tipWidth": 0.2,                 line width in mm (sets text-fill spacing)
      "xOffset": -1.1,                 mm, tip X position vs. your reference pen
      "drawSpeed": 20,                 optional, 1-110 %, overrides DrawSpeed
      "colors": ["Black", "Red",       empty list = any colour accepted
                 { "name": "Burgundy", "preview": "#800020" }]
    }

A colour is a name, which is also its preview colour when it's a .NET colour
name (Red, RoyalBlue, HotPink ...), or { "name", "preview" } with a .NET
name or #hex when it isn't. "note" and other keys are ignored. Keep
"schemaVersion": 2 and "units": "mm" at the top.

IMPORTANT: the xOffset values in the starter list were measured on one
machine and pen holder. Calibrate them on yours: plot a short line with your
reference pen (xOffset 0) and the same line with each other pen, measure
how far the second line lands to the right (+) or left (-) of the first,
and enter that in mm. A pen or colour a layer names that isn't in the list
stops the plot with a message, so nothing plots with a wrong offset.


7. WHERE LEAFMINER KEEPS ITS FILES
---------------------------------

Everything is in %APPDATA%\Leafminer:
  pen_profiles.json   your pen list
  axicli-py39\        axicli, installed for Rhino 8's Python
  plots\              the plot files (SVG); set Setup's Folder to change it

Uninstalling Leafminer from Rhino's Package Manager leaves this folder; delete
it yourself to remove everything.


8. TROUBLESHOOTING
------------------

- "AXICLI NOT INSTALLED": press Install axicli (section 2).
- Nothing happens on Plot: the Plotter's msg says which required input is
  empty (Geometry, BedSize, Control). Hover the red balloon for details.
- Unknown pen or colour: the layer name doesn't match the pen list. Compare
  it with the Pens output.
- The plot is shifted: zero was set in the wrong place, or the carriage was
  moved by hand. Press MotorsOff, move the carriage to the top-left corner,
  press MotorsOn.
- Several values in one input make the component run once per item; msg and
  the Report name such inputs.
- Part of the drawing is missing: anything past the plotter's travel is
  dropped. Check the bed size and Boundary.

Questions and bug reports: see the Food4Rhino page for the contact link.


9. LICENCE
----------

Leafminer is released under the MIT License - see LICENSE.txt.
axicli and the AxiDraw API are by Evil Mad Scientist Laboratories, under
their own licence; Leafminer downloads them from Evil Mad Scientist's site
and does not include them.
