From 802d81e63dcdeec4e5380bc4dd2bd9dc491350e5 Mon Sep 17 00:00:00 2001 From: Franklin Wei Date: Thu, 26 Dec 2019 01:42:05 -0500 Subject: Update README --- README.md | 117 ++++++++++++++++++++++++++++++++++++++++++------ rastercarve/__main__.py | 13 +++++- 2 files changed, 115 insertions(+), 15 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: + + + + +# 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. diff --git a/rastercarve/__main__.py b/rastercarve/__main__.py index 44a6f33..6a630ea 100755 --- a/rastercarve/__main__.py +++ b/rastercarve/__main__.py @@ -311,7 +311,16 @@ def main(): parser = argparse.ArgumentParser(prog='rastercarve', formatter_class=argparse.ArgumentDefaultsHelpFormatter, description='Generate G-code to engrave raster images.', - epilog='Defaults are usually safe to leave unchanged.') + epilog= + """ +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.""") parser.add_argument('filename', help='input image (any OpenCV-supported format)') dim_group = parser.add_argument_group('output dimensions', 'Exactly one required.') @@ -323,7 +332,7 @@ def main(): mach_group.add_argument('-f', help='engraving feed rate (in/min)', action='store', dest='feed_rate', default=DEF_FEED_RATE, type=float) mach_group.add_argument('-p', help='engraving plunge rate (in/min)', action='store', dest='plunge_rate', default=DEF_PLUNGE_RATE, type=float) mach_group.add_argument('--rapid', help='rapid traverse rate (for time estimation only)', action='store', dest='rapid_rate', default=DEF_RAPID_RATE, type=float) - mach_group.add_argument('-z', help='rapid Z traverse height (in)', action='store', dest='safe_z', default=DEF_SAFE_Z, type=float) + mach_group.add_argument('-z', help='rapid traverse height (in)', action='store', dest='safe_z', default=DEF_SAFE_Z, type=float) mach_group.add_argument('--end-z', help='Z height of final traverse (in)', action='store', dest='traverse_z', default=DEF_TRAVERSE_Z, type=float) mach_group.add_argument('-d', help='maximum engraving depth (in)', action='store', dest='max_depth', default=DEF_MAX_DEPTH, type=float) mach_group.add_argument('-t', help='included angle of tool (deg)', action='store', dest='tool_angle', default=DEF_TOOL_ANGLE, type=float) -- cgit v1.1