From a63c9715440f35fb1a4357761d2e4f19af34c467 Mon Sep 17 00:00:00 2001
From: Garth Minette <gminette@gmail.com>
Date: Mon, 22 Feb 2021 18:54:46 -0800
Subject: [PATCH] Vastly expanded docs for , with examples and images.

---
 constants.scad | 83 ++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 80 insertions(+), 3 deletions(-)

diff --git a/constants.scad b/constants.scad
index e67d2dd..c291bb7 100644
--- a/constants.scad
+++ b/constants.scad
@@ -10,9 +10,86 @@
 
 // Constant: $slop
 // Description:
-//   The printer specific amount of slop in mm to print with to make parts fit exactly.
-//   You may need to override this value for your printer.
-$slop = 0.20;
+//   A number of printers, particularly FDM/FFF printers, tend to be a bit sloppy in their printing.
+//   This has made it so that some parts won't fit together without adding a bit of extra slop space.
+//   That is what the `$slop` value is for.  The value for this will vary from printer to printer.
+//   By default, we use a value of 0.00 so that parts should fit exactly for resin and other precision
+//   printers.  This value is measured in millimeters.  When making your own parts, you should add
+//   `$slop` to both sides of a hole that another part is to fit snugly into. For a loose fit, add
+//   `2*$slop` to each side.  This should be done for both X and Y axes.  The Z axis will require a
+//   slop that depends on your layer height and bridging settings, and hole sizes.  We leave that as
+//   a more complicated exercise for the user.
+// DefineHeader(NumList): Calibration
+// Calibration: To calibrate the `$slop` value for your printer, follow this procedure:
+//   Print the Slop Calibration part from the example below.
+//   Take the long block and orient it so the numbers are upright, facing you.
+//   Take the plug and orient it so that the arrow points down, facing you.
+//   Starting with the hole with the largest number in front of it, insert the small end of the plug into the hole.
+//   If you can insert and remove the small end of the plug from the hole without much force, then try again with the hole with the next smaller number.
+//   Repeat step 5 until you have found the hole with the smallest number that the plug fits into without much force.
+//   The correct hole should hold the plug when the long block is turned upside-down.
+//   The number in front of that hole will indicate the `$slop` value that is ideal for your printer.
+//   Remember to set that slop value in your scripts after you include the BOSL2 library:  ie: `$slop = 0.15;`
+// Example: Slop Calibration Part.
+//   min_slop = 0.00;
+//   slop_step = 0.05;
+//   holes = 8;
+//   holesize = [15,15,15];
+//   height = 20;
+//   gap = 5;
+//   l = holes * (holesize.x + gap) + gap;
+//   w = holesize.y + 2*gap;
+//   h = holesize.z + 5;
+//   diff("holes")
+//   cuboid([l, w, h], anchor=BOT) {
+//     for (i=[0:holes-1]) {
+//       right((i-holes/2+0.5)*(holesize.x+gap)) {
+//         s = min_slop + slop_step * i;
+//         tags("holes") {
+//           cuboid([holesize.x + 2*s, holesize.y + 2*s, h+0.2]);
+//           fwd(w/2-1) xrot(90) linear_extrude(1.1) {
+//             text(
+//               text=fmt_fixed(s,2),
+//               size=0.4*holesize.x,
+//               halign="center",
+//               valign="center",
+//               font="Helvetica"
+//             );
+//           }
+//         }
+//       }
+//     }
+//   }
+//   back(holesize.y*2.5) {
+//     difference() {
+//       union() {
+//         cuboid([holesize.x+10, holesize.y+10, 15], anchor=BOT);
+//         cuboid([holesize.x, holesize.y, 15+holesize.z], anchor=BOT);
+//       }
+//       up(3) fwd((holesize.y+10)/2) {
+//         prismoid([holesize.x/2,1], [0,1], h=holesize.y-6);
+//       }
+//     }
+//   }
+// Example(2D): Where to add `$slop` gaps.
+//   $slop = 0.2;
+//   difference() {
+//     square([20,12],center=true);
+//     back(3) square([10+2*$slop,11],center=true);
+//   }
+//   back(8) {
+//     rect([15,5],anchor=FWD);
+//     rect([10,8],anchor=BACK);
+//   }
+//   color("#000") {
+//     xflip_copy()
+//       stroke([[5.1,6.1], [6.0,7.1], [8,7.1], [10.5,10]], width=0.3, endcap1="arrow2", endcap2="butt");
+//     xcopies(21) back(10.5) {
+//         back(1.2) text("$slop", size=1, halign="center");
+//         text("gap", size=1, halign="center");
+//     }
+//   }
+$slop = 0.0;
 
 
 // Constant: INCH