diff --git a/README.md b/README.md index 7ce26e1e..42bfb621 100644 --- a/README.md +++ b/README.md @@ -53,7 +53,7 @@ Some modules may depend on other modules. For example, the `polyline2d` module d - [box_extrude](https://openhome.cc/eGossip/OpenSCAD/lib-box_extrude.html) - [stereographic_extrude](https://openhome.cc/eGossip/OpenSCAD/lib-stereographic_extrude.html) - [turtle2d](https://openhome.cc/eGossip/OpenSCAD/lib-turtle2d.html) - + - [turtle3d](https://openhome.cc/eGossip/OpenSCAD/lib-turtle3d.html) ## Bugs and Feedback diff --git a/docs/images/lib-turtle3d-1.JPG b/docs/images/lib-turtle3d-1.JPG new file mode 100644 index 00000000..c085a2fb Binary files /dev/null and b/docs/images/lib-turtle3d-1.JPG differ diff --git a/docs/images/lib-turtle3d-2.JPG b/docs/images/lib-turtle3d-2.JPG new file mode 100644 index 00000000..df0b2b3a Binary files /dev/null and b/docs/images/lib-turtle3d-2.JPG differ diff --git a/docs/lib-turtle3d.md b/docs/lib-turtle3d.md new file mode 100644 index 00000000..32028c54 --- /dev/null +++ b/docs/lib-turtle3d.md @@ -0,0 +1,89 @@ +# turtle3d + +An OpenSCAD implementation of 3D Turtle Graphics. When using the function, imagine that you are sitting on the 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 + +- `cmd` : A string command. Different commands use different numbers of arguments. + - `"create"` : Creates a turtle data. The simplest way is `turtle3d("create")` which creates a turtle located at `[0, 0, 0]` (and unit vectors `[[1, 0, 0], [0, 1, 0], [0, 0, 1]]`). You can pass your own starting point and unit vectors, such as `turtle3d("create", [0, 0, 0], [[1, 0, 0], [0, 1, 0], [0, 0, 1]])`. + - `"xu_move"`, `"yu_move"`, `"zu_move"` : These commands need two arguments, the turtle data and the length you want to move from your viewpoint (you sit on the turtle). For example, `"turtle3d("xu_move", turtle, 10)"`. + - `"xu_turn"`, `"yu_turn"`, `"zu_turn"` : These commands need two arguments, the turtle data and the angle you want to turn from your viewpoint (you sit on the turtle). For example, `"turtle3d("xu_turn", turtle, 45)"`. + - `"pt"` : Gets the point of the turtle. It requires one argument, the turtle data. For example, `"turtle3d("pt", turtle)"`. + - `"unit_vts"` : Gets the unit vectors of the turtle. It requires one argument, the turtle data. For example, `"turtle3d("unit_vts", turtle)"`. + +## Examples + + include ; + include ; + + leng = 10; + angle = 120; + thickness = 1; + + t = turtle3d("create"); + + t2 = turtle3d("xu_move", t, leng); + hull_polyline3d( + [turtle3d("pt", t), turtle3d("pt", t2)], + thickness + ); + + t3 = turtle3d("xu_move", turtle3d("zu_turn", t2, angle), leng); + hull_polyline3d( + [turtle3d("pt", t2), turtle3d("pt", t3)], + thickness + ); + + t4 = turtle3d("xu_move", turtle3d("zu_turn", t3, angle), leng); + hull_polyline3d( + [turtle3d("pt", t3), turtle3d("pt", t4)], + thickness + ); + + +![turtle3d](images/lib-turtle3d-1.JPG) + + include ; + include ; + + module tree(t, leng, leng_scale1, leng_scale2, leng_limit, + angleZ, angleX, width) { + if(leng > leng_limit) { + t2 = turtle3d("xu_move", t, leng); + + hull_polyline3d( + [turtle3d("pt", t), turtle3d("pt", t2)], + width); + + tree( + turtle3d("zu_turn", t2, angleZ), + leng * leng_scale1, leng_scale1, leng_scale2, leng_limit, + angleZ, angleX, + width); + + tree( + turtle3d("xu_turn", t2, 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 = turtle3d("create"); + + tree(t, leng, leng_scale1, leng_scale2, leng_limit, + angleZ, angleX, width); + +![turtle3d](images/lib-turtle3d-2.JPG) diff --git a/src/turtle3d.scad b/src/turtle3d.scad new file mode 100644 index 00000000..b67ba54a --- /dev/null +++ b/src/turtle3d.scad @@ -0,0 +1,153 @@ +/** +* turtle3d.scad +* +* An OpenSCAD implementation of 3D Turtle Graphics. +* +* @copyright Justin Lin, 2017 +* @license https://opensource.org/licenses/lgpl-3.0.html +* +* @see https://openhome.cc/eGossip/OpenSCAD/lib-turtle3d.html +* +**/ + +function _turtle3d_x(pt) = pt[0]; +function _turtle3d_y(pt) = pt[1]; +function _turtle3d_z(pt) = pt[2]; + +function _turtle3d_pt3D(x, y, z) = [x, y, z]; + +function _turtle3d_create(pt, unit_vts) = [pt, unit_vts]; +function _turtle3d_create_default() = _turtle3d_create( + _turtle3d_pt3D(0, 0, 0), + // unit vectors from the turtle's viewpoint + [_turtle3d_pt3D(1, 0, 0), _turtle3d_pt3D(0, 1, 0), _turtle3d_pt3D(0, 0, 1)] +); + +function _turtle3d_plus(pt, n) = + _turtle3d_pt3D(_turtle3d_x(pt) + n, _turtle3d_y(pt) + n, _turtle3d_z(pt) + n); +function _turtle3d_minus(pt, n) = + _turtle3d_pt3D(_turtle3d_x(pt) - n, _turtle3d_y(pt) - n, _turtle3d_z(pt) + n); +function _turtle3d_mlt(pt, n) = + _turtle3d_pt3D(_turtle3d_x(pt) * n, _turtle3d_y(pt) * n, _turtle3d_z(pt) * n); +function _turtle3d_div(pt, n) = + _turtle3d_pt3D(_turtle3d_x(pt) / n, _turtle3d_y(pt) / n, _turtle3d_z(pt) / n); +function _turtle3d_neg(pt, n) = + _turtle3d_mlt(pt, -1); + +function _turtle3d_ptPlus(pt1, pt2) = + _turtle3d_pt3D( + _turtle3d_x(pt1) + _turtle3d_x(pt2), + _turtle3d_y(pt1) + _turtle3d_y(pt2), + _turtle3d_z(pt1) + _turtle3d_z(pt2) + ); + + +function _turtle3d_pt(turtle) = turtle[0]; +function _turtle3d_unit_vts(turtle) = turtle[1]; + +// forward the turtle in the x' direction +function _turtle3d_xu_move(turtle, leng) = _turtle3d_create( + _turtle3d_ptPlus(_turtle3d_pt(turtle), _turtle3d_mlt(_turtle3d_unit_vts(turtle)[0], leng)), + _turtle3d_unit_vts(turtle) +); + +// forward the turtle in the y' direction +function _turtle3d_yu_move(turtle, leng) = _turtle3d_create( + _turtle3d_ptPlus(_turtle3d_pt(turtle), _turtle3d_mlt(_turtle3d_unit_vts(turtle)[1], leng)), + _turtle3d_unit_vts(turtle) +); + +// forward the turtle in the z' direction +function _turtle3d_zu_move(turtle, leng) = _turtle3d_create( + _turtle3d_ptPlus( + _turtle3d_pt(turtle), + _turtle3d_mlt(_turtle3d_unit_vts(turtle)[2], leng) + ), + _turtle3d_unit_vts(turtle) +); + +// turn the turtle around the x'-axis +// return a new unit vector +function _turtle3d_xu_turn(turtle, a) = + let(cosa = cos(a), sina = sin(a)) + _turtle3d_create( + _turtle3d_pt(turtle), + [ + _turtle3d_unit_vts(turtle)[0], + _turtle3d_ptPlus( + _turtle3d_mlt(_turtle3d_unit_vts(turtle)[1], cosa), + _turtle3d_mlt(_turtle3d_unit_vts(turtle)[2], sina) + ), + _turtle3d_ptPlus( + _turtle3d_mlt(_turtle3d_neg(_turtle3d_unit_vts(turtle)[1]), sina), + _turtle3d_mlt(_turtle3d_unit_vts(turtle)[2], cosa) + ) + ] + ); + +// turn the turtle around the y'-axis +// return a new unit vector +function _turtle3d_yu_turn(turtle, a) = + let(cosa = cos(a), sina = sin(a)) + _turtle3d_create( + _turtle3d_pt(turtle), + [ + _turtle3d_ptPlus( + _turtle3d_mlt(_turtle3d_unit_vts(turtle)[0], cosa), + _turtle3d_mlt(_turtle3d_neg(_turtle3d_unit_vts(turtle)[2]), sina) + ), + _turtle3d_unit_vts(turtle)[1], + _turtle3d_ptPlus( + _turtle3d_mlt(_turtle3d_unit_vts(turtle)[0], sina), + _turtle3d_mlt(_turtle3d_unit_vts(turtle)[2], cosa) + ) + ] + ); + +// turn the turtle around the z'-axis +// return a new unit vector +function _turtle3d_zu_turn(turtle, a) = + let(cosa = cos(a), sina = sin(a)) + _turtle3d_create( + _turtle3d_pt(turtle), + [ + _turtle3d_ptPlus( + _turtle3d_mlt(_turtle3d_unit_vts(turtle)[0], cosa), + _turtle3d_mlt(_turtle3d_unit_vts(turtle)[1], sina) + ), + _turtle3d_ptPlus( + _turtle3d_mlt(_turtle3d_neg(_turtle3d_unit_vts(turtle)[0]), sina), + _turtle3d_mlt(_turtle3d_unit_vts(turtle)[1], cosa) + ), + _turtle3d_unit_vts(turtle)[2], + ] + ); + +function _turtle3d_create_cmd(arg1, arg2) = + (arg1 == undef && arg2 == undef) ? _turtle3d_create_default() : ( + (arg1 != undef && arg2 != undef) ? _turtle3d_create(arg1, arg2) : undef + ); + +function _turtle3d_chain_move(cmd, arg1, arg2) = + cmd == "xu_move" ? _turtle3d_xu_move(arg1, arg2) : ( + cmd == "yu_move" ? _turtle3d_yu_move(arg1, arg2) : ( + cmd == "zu_move" ? _turtle3d_zu_move(arg1, arg2) : _turtle3d_chain_turn(cmd, arg1, arg2) + ) + ); + +function _turtle3d_chain_turn(cmd, arg1, arg2) = + cmd == "xu_turn" ? _turtle3d_xu_turn(arg1, arg2) : ( + cmd == "yu_turn" ? _turtle3d_yu_turn(arg1, arg2) : ( + cmd == "zu_turn" ? _turtle3d_zu_turn(arg1, arg2) : _turtle3d_chain_one_arg(cmd, arg1) + ) + ); + +function _turtle3d_chain_one_arg(cmd, arg) = + cmd == "pt" ? _turtle3d_pt(arg) : ( + cmd == "unit_vts" ? _turtle3d_unit_vts(arg) : undef + ); + +function turtle3d(cmd, arg1, arg2) = + cmd == "create" ? + _turtle3d_create_cmd(arg1, arg2) : + _turtle3d_chain_move(cmd, arg1, arg2); \ No newline at end of file