update documentation

README.md

@@ -4,16 +4,39 @@ Tools for generating physical keys.
 ![Key in Inkscape](doc/inkscape.png "SC4")
 ![Key in OpenSCAD](doc/key.png "152698")
 
-## How it Works
+## How to use it
-1. Get some nice pictures of the side and tip of your key.
+```
-I recommend a flatbed scanner.
+usage: keygen.py [-h] [-b BITTING] [-u OUTLINE] [-w WARDING] [-o OUTPUT]
-2. Trace the key outline, warding, and engraving in Inkscape
+                 filename
-3. Use the provided Inkscape plugin to convert the paths to OpenSCAD polygons.
+
-4. Look up online the various parameters of your key, such as plug diameter,
+Generates keys.
-cut depths and locations.
+
-5. Use the provided OpenSCAD functions `key_code_to_heights`,
+positional arguments:
-`key_blank` and `key_bitting` to generate a 3D model of your key.
+  filename              OpenSCAD source file for the key
-6. Send the key to be 3D printed.
+
+optional arguments:
+  -h, --help            show this help message and exit
+  -b BITTING, --bitting BITTING
+                        Key bitting
+  -u OUTLINE, --outline OUTLINE
+                        Key blank outline
+  -w WARDING, --warding WARDING
+                        Key warding
+  -o OUTPUT, --output OUTPUT
+                        Output file (defaults to a.stl)
+
+All remaining arguments are passed to OpenSCAD.
+```
+
+### Examples
+
+```bin/keygen.py scad/schlage_classic.scad --bitting 25536 -o housekey.stl```
+```bin/keygen.py scad/schlage_classic.scad -u 6-pin -w L -b 999999 -o all_section_bump_key.stl```
+```bin/keygen.py scad/schlage_classic.scad -o key.png --render```
+
+## Contributing
+
+There is a very limited selection of keys right now, to help out, see the guide on [how to model keys](doc/how_to_model_keys.md).
 
 ## Music
 

bin/keygen.py

@@ -6,7 +6,7 @@ import string
 import sys
 import subprocess
 
-parser = argparse.ArgumentParser(description='Generates keys', epilog='All remaining arguments are passed to OpenSCAD.')
+parser = argparse.ArgumentParser(description='Generates keys.', epilog='All remaining arguments are passed to OpenSCAD.')
 parser.add_argument("filename",
                     help="OpenSCAD source file for the key")
 parser.add_argument("-b", "--bitting", dest='bitting',

doc/how_to_model_keys.md

@@ -0,0 +1,44 @@
+# How to model a new key
+
+![Key in Inkscape](inkscape.png "SC4")
+![Key in OpenSCAD](key.png "152698")
+
+## How it Works
+1. Get some nice pictures of the side and tip of your key.
+I recommend a flatbed scanner.
+You may also consider finding a profile of your key in a [PDF
+from the manufacturer](https://www.imlss.com/images/pdf/KBD12.pdf).
+2. Using Inkscape, trace the key outline, warding, and engraving.
+If you got your image from a PDF, your job is much easier,
+and you only need to clean up the paths.
+3. Select a path and press `Control-Shift-O`. Give it a useful name, such as "outline" or "warding".
+4. Save the result as a SVG in the `resources` folder. Run `make` to generate OpenSCAD polygons from your paths.
+5. Look up online the various parameters of your key, such as plug diameter,
+cut depths and locations.
+5. Use the provided OpenSCAD functions `key_code_to_heights`,
+`key_blank` and `key_bitting` to generate a 3D model of your key.
+Use the provided OpenSCAD files as a template.
+6. To add your key to the database,
+edit the `Makefile` to include your `.scad` file in the `SCAD_SRC` variable.
+
+For this to work, your final file must look like this:
+
+```
+module key_name(...) {
+    name = "Human-readable name of your key";
+    /*
+        Description of your key, including
+        how to properly format a bitting,
+        possibly with examples
+    */
+
+    ...
+}
+
+// These defaults are overridden by
+// -D on the command line
+bitting = "default-bitting";
+outline = "default-outline";
+warding = "default-warding";
+key_name(...);
+```