Release 0.2

.gitignore

@@ -0,0 +1,4 @@
+.DS_Store
+*.xcf
+.*.swp
+design/THREAD_TABLE.csv

README.rst

@@ -1,53 +1,98 @@
-threadlib
+.. image:: docs/imgs/logo.png
-+++++++++++++++++++++++++++
+        :alt: bolt-in-nut logo
 
-threadlib is a library of standard threads for OpenSCAD. It is based on Helges
+threadlib is a library of standard threads for `OpenSCAD <https://www.openscad.org>`__.
-excellent `threadprofile.scad
+It is based on Helges excellent
-<https://github.com/MisterHW/IoP-satellite/tree/master/OpenSCAD%20bottle%20threads>`__
+`threadprofile.scad <https://github.com/MisterHW/IoP-satellite/tree/master/OpenSCAD%20bottle%20threads>`__
-to create nice threads with lead-in / lead-out tapers. Check out his `article on
+to create nice threads with lead-in / lead-out tapers. Check out his `article on generating nice threads <https://hackaday.io/page/5252-generating-nice-threads-in-openscad>`__
-generating nice threads
+on Hackaday.
-<https://hackaday.io/page/5252-generating-nice-threads-in-openscad>`__ on
-Hackaday.
 
-In contrast to other thread libraries, threadlib does not make you look up
+In contrast to other thread libraries such as `openscad-threads <http://dkprojects.net/openscad-threads/>`__,
-diameters and pitches and maybe even thread-profiles in tables and norms: It has
+`yet another thread library <https://www.thingiverse.com/thing:2277141>`__,
-these tables built in.
+`threads for screws and nuts V1 <https://www.thingiverse.com/thing:3131126>`__,
+and `threading.scad <https://www.thingiverse.com/thing:1659079>`__,
+threadlib does not make you look up diameters and pitches and maybe even
+thread-profiles in tables and norms: It has these tables built in.
 
 Creating a thread is as simple as
 
 .. code-block:: OpenSCAD
 
-        thread("G1/2-ext", turns=10, higbee_arc=20);
+        use <threadlib/threadlib.scad>
+        thread("G1/2-ext", turns=10);
 
-to create a British Standard Pipe parallel external thread. Furthermore,
+.. image:: docs/imgs/thread-G1o2-ext-10turns.png
-threadlib allows for production tolerances by choosing thread dimensions well
+        :alt: bolt-in-nut logo
-inside the ranges allowed by the norms.
+
+to create a British Standard Pipe parallel external thread. 
+
+
+==================================
+Why you may want to use threadlib
+==================================
+
+- really easy to use
+- creates nice threads
+- configurable higbee arc
+- creates working threads (clearances are left for production tolerances)
+- flexible:
+  - choose the $fn you need to fit the rest of your design
+  - let threadlib tell you the thread specs so you can do with them what *you* want
+- extensible: Add your own threads
+- tried and tested in the real world: Um no, not yet. But with your help, it
+  will soon be.
+
+
+Installation
+===========================
+
+Prerequisits:
+
+- `scad-utils <https://github.com/openscad/scad-utils>`__
+- `list-comprehension <https://github.com/openscad/list-comprehension-demos>`__
+- `threadprofile.scad <https://github.com/MisterHW/IoP-satellite/blob/master/OpenSCAD%20bottle%20threads/thread_profile.scad>`__
+  
+Save all of these into your OpenSCAD `library folder <https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/Libraries>`__
+
+threadlib:
+
+Clone threadlib into the folder 'threadlib' inside your OpenSCAD library folder
 
 
 Usage
 ===========================
 
-To create a bolt (without head) with 10 turns of G1-inch thread:
+To create a bolt (without head) with 5 turns of M4 thread:
 
 .. code-block:: OpenSCAD
 
-        bolt("G1", turns=10);
+        bolt("M4", turns=5, higbee_arc=30);
 
-A nut:
+.. image:: docs/imgs/bolt-M4.png
+        :alt: Bolt with M4 thread
+
+See these nice lead-in / lead-out tapers? Try a nut (this time using the default
+argument for higbee_arc):
 
 .. code-block:: OpenSCAD
 
-        nut("G1", turns=10, Douter=40);
+        nut("M12x0.5", turns=10, Douter=16);
+
+.. image:: docs/imgs/nut-M12x0.5.png
+        :alt: M12x0.5 nut
 
 Note that for a nut you also have to specify an outer diameter. The inner
-diameter is implicitly given by the thread designator ("G1" in this case).
+diameter is implicitly given by the thread designator ("M12x0.5" in this case).
 
 If you only need the threads alone:
 
 .. code-block:: OpenSCAD
 
-        thread("G2 1/2-ext", turns=5);
+        thread("G1/2-ext", turns=5);
 
+.. image:: docs/imgs/thread-G1o2-ext.png
+        :alt: G1/2 external thread
+ 
 Then, add the support you want. In the simplest case, a cylinder (which is what
 nut(...) uses):
 
@@ -60,6 +105,9 @@ nut(...) uses):
         translate([0, 0, -P / 2])
             cylinder(h=H, d=Dsupport, $fn=120);
 
+.. image:: docs/imgs/flexible.png
+        :alt: G1/2 bolt
+
 Here, we have used the function thread_specs(...) to look up the threads
 specifications - including the recommended diameter of the support structure.
 
@@ -69,7 +117,9 @@ List of supported threads
 
 Currently, threadlib knows these threads:
 
-- British Standard Pipe Parallel Threadss G1/16 to G6
+- `Metric threads <http://mdmetric.com/tech/M-thead%20600.htm>`__ (coarse, fine, and super-fine pitches) M0.25 to M600
+- `BSP parallel thread <https://www.amesweb.info/Screws/British-Standard-Pipe-Parallel-Thread-BSPP.aspx>`__ G1/16 to G6
+- `PCO-1881 <https://www.bevtech.org/assets/Committees/Packaging-Technology/20/3784253-20.pdf>`__ (PET-bottle thread)
 
 
 Extensibility
@@ -97,5 +147,6 @@ for addition to threadlib!
 Change Log
 ===========================
 
-- 0.1: Initial release supporting BSP parallel thread
+- 0.2: `Metric threads <http://mdmetric.com/tech/M-thead%20600.htm>`__, `PCO-1881 <https://www.bevtech.org/assets/Committees/Packaging-Technology/20/3784253-20.pdf>`__
+- 0.1: Initial release supporting `BSP parallel thread <https://www.amesweb.info/Screws/British-Standard-Pipe-Parallel-Thread-BSPP.aspx>`__
 

autogenerate.awk

@@ -1,5 +0,0 @@
-BEGIN	{ print "/* This script is auto-generated - do not edit"
-	  print "   :License: 3-clause BSD. See LICENSE. */"
-	  printf "\nTHREAD_TABLE = [" }
-/^G/	{ print "[\"" $1 "\", [" $2 ", " $3 ", " $4 ", [[" $5 ", " $6 "], [" $7 ", " $8 "], [" $9 ", " $10 "], [" $11 ", " $12 "]]]],"}
-END	{ print "];" }

design/autogenerate.awk

@@ -0,0 +1,6 @@
+BEGIN	{ FS = "," ; RS = "\n"
+	  print "/* This script is auto-generated - do not edit"
+	  print "   :License: 3-clause BSD. See LICENSE. */"
+	  printf "\nTHREAD_TABLE = [" }
+/^[GPM]/	{ print "[\"" $1 "\", [" $2 ", " $3 ", " $4 ", [[" $5 ", " $6 "], [" $7 ", " $8 "], [" $9 ", " $10 "], [" $11 ", " $12 "]]]],"}
+END	{ print "];" }

docs/Makefile

@@ -0,0 +1,28 @@
+os = /usr/local/bin/openscad
+opts =
+imgs = bolt-M4.png nut-M12x0.5.png nutNbolt.png thread-G1o2-ext.png thread-G1o2-ext-10turns.png flexible.png
+
+.PHONY: all
+all: $(imgs)
+
+bolt-M4.png: bolt.scad
+	$(os) $(opts) --D 'type="M4"' --D 'turns=5' --D 'higbee_arc=30' --camera=0.49,-0.26,1.55,74.6,0.0,78.9,20 --imgsize=2048,2048 -o $@ $<
+
+nut-M12x0.5.png: nut.scad
+	$(os) $(opts) --D 'type="M12x0.5"' --D 'turns=10' --D 'higbee_arc=20' --D 'Douter=16' --camera=-2.2,1.2,1.8,66,0,73,52 --imgsize=2048,2048 --projection=ortho -o $@ $<
+
+nutNbolt.png: nutNbolt.scad
+	$(os) $(opts) --camera=-0.24,1.19,4.24,83,0,326.9,40.3 --imgsize=2048,2048 --projection=ortho -o $@ $<
+
+thread-G1o2-ext-10turns.png: thread.scad
+	$(os) $(opts) --D 'type="G1/2-ext"' --D 'turns=10' --D 'higbee_arc=20' --camera=-0.7,-0.6,3.4,75,0,110,100 --imgsize=2048,2048 --projection=ortho -o $@ $<
+
+thread-G1o2-ext.png: thread.scad
+	$(os) $(opts) --D 'type="G1/2-ext"' --D 'turns=5' --D 'higbee_arc=20' --camera=-0.7,-0.6,3.4,75,0,110,57 --imgsize=2048,2048 --projection=ortho -o $@ $<
+
+flexible.png: flexible.scad
+	$(os) $(opts) --D 'type="G1/2-ext"' --D 'turns=5' --D 'higbee_arc=20' --camera=-0.7,-0.6,3.4,75,0,110,57 --imgsize=2048,2048 --projection=ortho -o $@ $<$
+
+.PHONY: clean
+clean:
+	rm *.png

docs/bolt.scad

@@ -0,0 +1,15 @@
+/*
+Create nice previews for documentation
+
+:Author: Adrian Schlatter
+:Date: 2019-04-10
+:License: 3-Clause BSD. See LICENSE.
+*/
+
+use <threadlib/threadlib.scad>
+
+type = "M6";
+turns = 5;
+higbee_arc = 45;
+
+bolt(type, turns, higbee_arc=higbee_arc);

docs/flexible.scad

@@ -0,0 +1,22 @@
+/*
+Create nice previews for documentation
+
+:Author: Adrian Schlatter
+:Date: 2019-04-13
+:License: 3-Clause BSD. See LICENSE.
+*/
+
+use <threadlib/threadlib.scad>
+
+type = "G1/2-ext";
+turns = 5;
+higbee_arc = 20;
+
+thread(type, turns, higbee_arc=higbee_arc);
+
+specs = thread_specs(type);
+P = specs[0]; Rrot = specs[1]; Dsupport = specs[2];
+section_profile = specs[3];
+H = (turns + 1) * P;
+translate([0, 0, -P / 2])
+    cylinder(h=H, d=Dsupport, $fn=120);

docs/nut.scad

@@ -0,0 +1,16 @@
+/*
+Create nice previews for documentation
+
+:Author: Adrian Schlatter
+:Date: 2019-04-10
+:License: 3-Clause BSD. See LICENSE.
+*/
+
+use <threadlib/threadlib.scad>
+
+type = "M12x0.5";
+turns = 10;
+Douter = 16;
+higbee_arc = 45;
+
+nut(type, turns, Douter, higbee_arc=higbee_arc);

docs/nutNbolt.scad

@@ -0,0 +1,26 @@
+/*
+Create nice previews for documentation
+
+:Author: Adrian Schlatter
+:Date: 2019-04-10
+:License: 3-Clause BSD. See LICENSE.
+*/
+
+use <threadlib/threadlib.scad>
+
+type = "M6";
+turns = 6;
+higbee_arc = 45;
+
+P = thread_specs(str(type, "-ext"))[0];
+dz = (turns / 2 - 1/4) * P;
+Douter = thread_specs(str(type, "-int"))[2] * 1.5;
+
+translate([0, 0, dz])
+    rotate([0, 0, -90])
+        bolt(type, turns, higbee_arc=higbee_arc);
+intersection() {
+    nut(type, turns, Douter, higbee_arc=higbee_arc);
+    translate([-100, 0, 0])
+        cube([200, 200, 200]);
+};

docs/thread.scad

@@ -0,0 +1,15 @@
+/*
+Create nice previews for documentation
+
+:Author: Adrian Schlatter
+:Date: 2019-04-13
+:License: 3-Clause BSD. See LICENSE.
+*/
+
+use <threadlib/threadlib.scad>
+
+type = "G1/2-ext";
+turns = 10;
+higbee_arc = 45;
+
+thread(type, turns, higbee_arc=higbee_arc);

tests/test.scad

@@ -10,14 +10,15 @@ use <threadlib/threadlib.scad>
 
 echo ("threadlib version: ", __THREADLIB_VERSION());
 
-type = "G1";
+type = "M12x0.5";
 turns = 5;
 Douter = thread_specs(str(type, "-int"))[2] * 1.2;
 
+echo(thread_specs(str(type, "-ext")));
 intersection() {
     color("Green")
-        translate([-100, 0, -100])
+        translate([-1000, 0, -1000])
-            cube(200, 200, 200);
+            cube(2000, 2000, 2000);
     union() {
         bolt(type, turns);
         nut(type, turns, Douter);

threadlib.scad

@@ -9,7 +9,7 @@ Create threads easily.
 :License: 3-Clause BSD. See LICENSE.
 */
 
-function __THREADLIB_VERSION() = 0.1;
+function __THREADLIB_VERSION() = 0.2;
 
 use <thread_profile.scad>
 include <THREAD_TABLE.scad>