diff --git a/docs/images/lib2-t3d-1.JPG b/docs/images/lib2-t3d-1.JPG new file mode 100644 index 00000000..03e5de39 Binary files /dev/null and b/docs/images/lib2-t3d-1.JPG differ diff --git a/docs/images/lib2-t3d-2.JPG b/docs/images/lib2-t3d-2.JPG new file mode 100644 index 00000000..5528e87e Binary files /dev/null and b/docs/images/lib2-t3d-2.JPG differ diff --git a/docs/lib2-t3d.md b/docs/lib2-t3d.md new file mode 100644 index 00000000..4fdb4606 --- /dev/null +++ b/docs/lib2-t3d.md @@ -0,0 +1,84 @@ +# t3d + +An implementation of 3D Turtle Graphics with Fluent API. When using the function, imagine that you are sitting on a turtle. You move or turn the turtle from the your viewpoint, not the viewpoint of OpenSCAD coordinates. + +For more details, please see [3D turtle graphics](https://openhome.cc/eGossip/OpenSCAD/3DTurtleGraphics.html). + +## Parameters + +- `t` : The data of a turtle. `t3d()` with no arguments will return a turtle with the point `[0, 0, 0]` and the unit vectors `[[1, 0, 0], [0, 1, 0], [0, 0, 1]]`. +- `cmd` : It accepts a string or a list of commands. + - Given a string: `"xturn"`, `"yturn"`, `"zturn"`, `"xforward"`, `"yforward"`, `"zforward"`, `"point"` or `"unit_vectors"`. If `"xturn"`, `"yturn"` or `"zturn"` is provided, the `angle` parameter is required. If `"xforward"`, `"yforward"` or `"zforward"` is provided, `leng` is required. `"point"` and `"unit_vectors"` are used to get respective data from a turtle. + - Given a list: `[[cmd1, value], [cmd2, value2], ...]`. For example, `[["xforward", 10], ["zturn", 120]]` will forward a turtle 10mm along the x axis and turn it 120 degrees around the z axis from your viewpoint. +- `point` : Set the position of a turtle. +- `unit_vectors` : Set the unit vectors of a turtle. +- `angle` : Set the angle of a turtle if `cmd` is not provided. Turn a turtle if `cmd` is `"turn"`. +- `leng` : Forward a turtle if `cmd` is `"forward"`. + +## Examples + + include ; + include ; + + leng = 10; + angle = 120; + thickness = 1; + + t = t3d(point = [0, 0, 0]); + t2 = t3d(t, "xforward", leng = leng); + t3 = t3d(t2, [ + ["zturn", angle], + ["xforward", leng] + ]); + t4 = t3d(t3, [ + ["zturn", angle], + ["xforward", leng] + ]); + + hull_polyline3d( + [for(turtle = [t, t2, t3, t4]) t3d(turtle, "point")], + thickness + ); + +![t3d](images/lib2-t3d-1.JPG) + + include ; + include ; + + module tree(t, leng, leng_scale1, leng_scale2, leng_limit, + angleZ, angleX, width) { + if(leng > leng_limit) { + t2 = t3d(t, "xforward", leng = leng); + + line3d( + t3d(t, "point"), t3d(t2, "point"), + width); + + tree( + t3d(t2, "zturn", angle = angleZ), + leng * leng_scale1, leng_scale1, leng_scale2, leng_limit, + angleZ, angleX, + width); + + tree( + t3d(t2, "xturn", angle = angleX), + leng * leng_scale2, leng_scale1, leng_scale2, leng_limit, + angleZ, angleX, + width); + } + } + + leng = 100; + leng_limit = 1; + leng_scale1 = 0.4; + leng_scale2 = 0.9; + angleZ = 60; + angleX = 135; + width = 2; + + t = t3d(point = [0, 0, 0]); + + tree(t, leng, leng_scale1, leng_scale2, leng_limit, + angleZ, angleX, width); + +![t2d](images/lib2-t3d-2.JPG)