Update README

1 files changed, 104 insertions, 13 deletions

diff --git a/README.md b/README.md
index 40fae72..c9d27c4 100644
--- a/README.md
+++ b/README.md
@@ -1,13 +1,99 @@
-# RasterCarve: Generate G-code to engrave raster images
+# RasterCarve
 
-This is a little Python script I wrote to generate 3-axis toolpaths to
+This is a little Python script I wrote to generate G-code toolpaths to
 engrave raster images.
 
-## Installation
+It takes bitmap images and produces commands (G-code) for a CNC
+machine to engrave that image onto a piece of material. For the
+uninitiated, a CNC machine is essentially a robotic carving machine --
+think *robot drill*: you 1) put in a piece of wood/foam/aluminum
+stock; 2) program the machine; and 3) out comes a finished piece with
+the right patterns cut into it.
 
-`pip install rastercarve`
+This program comes in during step 2 -- it takes an image and outputs
+the right sequence of commands for your machine to engrave it. This is
+not the first program that can do this, but existing solutions are
+unsuitable due to their high cost.
 
-## Usage
+Examples below:
+
+<img src="https://www.fwei.tk/blog/d-day.jpg" width="40%">
+<img src="https://www.fwei.tk/blog/baby-yoda.png" width="40%">
+
+# Installation
+
+`$ pip install rastercarve`
+
+Running straight from the source tree works fine, too:
+
+`$ python -m rastercarve -h`
+
+# Usage
+
+```
+$ rastercarve --width 10 examples/test.png > out.nc
+Generating G-code: 100%|██████████████████| 278/278 [00:04<00:00, 57.10 lines/s]
+=== Statistics ===
+Input resolution: 512x512 px
+Output dimensions: 10.00" wide by 10.00" tall = 100.0 in^2
+Max line depth: 0.080 in
+Max line width: 0.043 in (30.0 deg V-bit)
+Line spacing: 0.047 in (110% stepover)
+Line angle: 22.5 deg
+Number of lines: 277
+Input resolution:  51.2 PPI
+Output resolution: 100.0 PPI
+Scaled image by f=3.91 (200.0 PPI)
+Total toolpath length: 2202.6 in
+ - Rapids:  34.6 in (8.6 s)
+ - Plunges: 29.8 in (59.6 s)
+ - Moves:   2138.2 in (1282.9 s)
+Feed rate: 100.0 in/min
+Plunge rate: 30.0 in/min
+Estimated machining time: 1351.2 sec
+1 suppressed debug message(s).
+```
+
+This command generates G-code to engrave `examples/test.png` into an
+piece of material 10 inches wide. Exactly one of the `--width` or
+`--height` parameters must be specified on the command line; the other
+will be calculated automatically.
+
+The engraving parameters can be safely left at their defaults, though
+fine-tuning is possible depending on material and machine
+characteristics.
+
+The output G-code will be piped to `out.nc`, which any CNC machine
+should accept as input.
+
+# Machining Process
+
+With the toolpath generated, it is time to run the job. Presumably you
+know the specifics of your particular machine, so I'll only outline
+the high-level steps here:
+
+1. Load the right tool. An engraving bit is best, though ordinary
+V-bits give acceptable results. Make sure that the tool angle matches
+that used to generate the toolpath (30 degrees is the default --
+change this if needed).
+
+2. Load the material. MDF seems to work best; plywood and ordinary
+lumber are too prone to chipping. Plastics have a tendency to melt and
+stick to the bit.
+
+3. Zero X and Y axes at the top left corner of the eventual image
+location. Double check that the bottom right corner is in bounds.
+
+4. Zero the Z axis to the top surface of the material.
+
+5. Load and run the toolpath. The engraving will begin in the top
+right corner and work its way down to the bottom right in a serpentine
+fashion.
+
+The program's output has been tested on a ShopBot Desktop MAX, which
+produced the results shown earlier.
+
+# Advanced
 
 ```
 usage: rastercarve [-h] (--width WIDTH | --height HEIGHT) [-f FEED_RATE]
@@ -39,7 +125,7 @@ machine configuration:
   -p PLUNGE_RATE        engraving plunge rate (in/min) (default: 30)
   --rapid RAPID_RATE    rapid traverse rate (for time estimation only)
                         (default: 240)
-  -z SAFE_Z             rapid Z traverse height (in) (default: 0.1)
+  -z SAFE_Z             rapid traverse height (in) (default: 0.1)
   --end-z TRAVERSE_Z    Z height of final traverse (in) (default: 2)
   -d MAX_DEPTH          maximum engraving depth (in) (default: 0.08)
   -t TOOL_ANGLE         included angle of tool (deg) (default: 30)
@@ -54,14 +140,19 @@ engraving parameters:
 G-code parameters:
   --no-line-numbers     suppress G-code line numbers (dangerous on ShopBot!)
 
-Defaults are usually safe to leave unchanged.
+The default feeds have been found to be safe values for medium-density
+fiberboard (MDF). Experimenting with the STEPOVER, LINE_ANGLE, and
+LINEAR_RESOLUTION may yield improvements in engraving quality at the cost of
+increased machining time. On ShopBot machines, the --no-line-numbers flag must
+not be used, since the spindle will fail to start and damage the material. Use
+this flag with caution on other machines.
 ```
 
-### Examples
+# Related
 
-```
-rastercarve --width 10 examples/test.png > out.nc
-```
+[Vectric PhotoVCarve](https://www.vectric.com/products/photovcarve) -
+a similar commercial solution. This program is not derived from
+PhotoVCarve.
 
-Generate G-code to engrave `examples/test.png` into an image 10 inches
-wide. Output will be piped from stdout to `out.nc`.
+[My blog post](https://www.fwei.tk/blog/opening-black-boxes.html) -
+writeup on the development process.