omdl  v0.9.5
OpenSCAD Mechanical Design Library
align.scad
Go to the documentation of this file.
1 //! Shape alignment tools.
2 /***************************************************************************//**
3  \file
4  \author Roy Allen Sutton
5  \date 2017-2019
6 
7  \copyright
8 
9  This file is part of [omdl] (https://github.com/royasutton/omdl),
10  an OpenSCAD mechanical design library.
11 
12  The \em omdl is free software; you can redistribute it and/or modify
13  it under the terms of the [GNU Lesser General Public License]
14  (http://www.gnu.org/licenses/lgpl.html) as published by the Free
15  Software Foundation; either version 2.1 of the License, or (at
16  your option) any later version.
17 
18  The \em omdl is distributed in the hope that it will be useful,
19  but WITHOUT ANY WARRANTY; without even the implied warranty of
20  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
21  Lesser General Public License for more details.
22 
23  You should have received a copy of the GNU Lesser General Public
24  License along with the \em omdl; if not, write to the Free Software
25  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
26  02110-1301, USA; or see <http://www.gnu.org/licenses/>.
27 
28  \details
29 
30  \amu_define group_name (Alignment)
31  \amu_define group_brief (Shape alignment tools.)
32 
33  \amu_include (include/amu/pgid_path_pstem_pg.amu)
34 *******************************************************************************/
35 
36 //----------------------------------------------------------------------------//
37 // group.
38 //----------------------------------------------------------------------------//
39 
40 /***************************************************************************//**
41  \amu_include (include/amu/group_in_parent_start.amu)
42  \amu_include (include/amu/includes_required.amu)
43 *******************************************************************************/
44 
45 //----------------------------------------------------------------------------//
46 
47 //! Orient a line or vector to a reference line or vector.
48 /***************************************************************************//**
49  \param l <line-3d | line-2d> The line or vector to align.
50  \param r <line-3d | line-2d> The reference line or vector.
51 
52  \param ar <decimal> Axial roll about \p r (in degrees).
53 
54  \details
55 
56  See \ref dt_line for argument specification and conventions.
57 *******************************************************************************/
58 module orient_ll
59 (
60  l = z_axis3d_ul,
61  r = z_axis3d_ul,
62  ar = 0
63 )
64 {
65  ll = vol_to_origin(l);
66  lr = vol_to_origin(r);
67 
68  rotate(ar, lr)
69  rotate(angle_ll(ll, lr), cross(ll, lr))
70  children();
71 }
72 
73 //! Align a line or vector to a reference line or vector.
74 /***************************************************************************//**
75  \param l <line-3d | line-2d> The line or vector to align.
76  \param r <line-3d | line-2d> The reference line or vector.
77 
78  \param lp <integer> The line alignment point (see table).
79  \param rp <integer> The reference-line alignment point (see table).
80 
81  \param ar <decimal> Axial roll about \p r (in degrees).
82 
83  \param to <vector-3d | vector-2d> Translation offset about \p r.
84  \param ro <decimal-list-1:3 | decimal> Rotation offset about \p r
85  (in degrees).
86 
87  \details
88 
89  The specified alignment point for the line \p l will be a translated
90  to the specified alignment point for the reference line \p r.
91 
92  | lp, rp | alignment point |
93  |:-------:|:----------------------|
94  | 0 | none (no translation) |
95  | 1 | initial |
96  | 2 | median |
97  | 3 | termination |
98  | 4 | initial + termination |
99 
100  See \ref dt_line for argument specification and conventions.
101 *******************************************************************************/
102 module align_ll
103 (
104  l = z_axis3d_ul,
105  r = z_axis3d_ul,
106  lp = 0,
107  rp = 0,
108  ar = 0,
109  to = origin3d,
110  ro = zero3d
111 )
112 {
113  li = point_to_3d(line_ip(l));
114  lt = point_to_3d(line_tp(l));
115 
116  ri = point_to_3d(line_ip(r));
117  rt = point_to_3d(line_tp(r));
118 
119  ll = [li, lt];
120  lm = mean(ll);
121 
122  lr = [ri, rt];
123  rm = mean(lr);
124 
125  // translate reference
126  translate(select_ci([origin3d, ri, rm, rt, ri+rt, rm], rp))
127 
128  // orient and roll line about reference
129  rotate(ar, vol_to_origin(lr))
130  rotate(angle_ll(ll, lr), cross_ll(ll, lr))
131 
132  // apply offsets
133  translate(to)
134  rotate(ro)
135 
136  // translate alignment point
137  translate(-select_ci([origin3d, li, lm, lt, li+lt, lm], lp))
138  children();
139 }
140 
141 //! Align an objects Cartesian axis to reference line or vector.
142 /***************************************************************************//**
143  \param a <integer> The Cartesian axis index to align
144  (\b x_axis_ci, \b y_axis_ci, or \b z_axis_ci).
145  \param r <line-3d | line-2d> The reference line or vector.
146 
147  \param rp <integer> The reference-line alignment point (see table).
148 
149  \param ar <decimal> Axial roll about \p r (in degrees).
150 
151  \param to <vector-3d | vector-2d> Translation offset about \p r.
152  \param ro <decimal-list-1:3 | decimal> Rotation offset about \p r
153  (in degrees).
154 
155  \details
156 
157  The origin will be a translated to the specified alignment point
158  for the reference line \p r.
159 
160  | rp | alignment point |
161  |:-------:|:----------------------|
162  | 0 | none (no translation) |
163  | 1 | initial |
164  | 2 | median |
165  | 3 | termination |
166  | 4 | initial + termination |
167 
168  See \ref dt_line for argument specification and conventions.
169 *******************************************************************************/
170 module align_al
171 (
172  a = z_axis_ci,
173  r = z_axis3d_ul,
174  rp = 0,
175  ar = 0,
176  to = origin3d,
177  ro = zero3d
178 )
179 {
181 
182  align_ll(ra, r, 0, rp, ar, to, ro)
183  children();
184 }
185 
186 //! @}
187 //! @}
188 
189 //----------------------------------------------------------------------------//
190 // end of file
191 //----------------------------------------------------------------------------//
z_axis3d_ul
<line-3d> A positively-directed unit line centered on the z-axis in 3d Euclidean space.
Definition: constants.scad:443
z_axis_ci
<integer> The coordinate axis index for the Euclidean space z-axis.
Definition: constants.scad:401
origin3d
<point-3d> The origin point coordinate in 3-dimensional Euclidean space.
Definition: constants.scad:425
y_axis3d_ul
<line-3d> A positively-directed unit line centered on the y-axis in 3d Euclidean space.
Definition: constants.scad:440
x_axis3d_ul
<line-3d> A positively-directed unit line centered on the x-axis in 3d Euclidean space.
Definition: constants.scad:437
zero3d
<decimal-list-2> A 3d zero vector (a list with three zeros).
Definition: constants.scad:422
function line_tp(l)
Return the terminal point of a line or vector.
function angle_ll(l1, l2, s=true)
Compute the angle between two lines or vectors in a 3d or 2d-space.
function vol_to_origin(l)
Convert line to vector by shifting it to the origin.
function point_to_3d(p)
Return 3d point unchanged or add a zeroed third dimension to 2d point.
function line_ip(l)
Return the initial point of a line or vector.
function cross_ll(l1, l2)
Compute the cross product of two lines or vectors in a 3d or 2d-space.
function mean(v)
Compute the mean/average of a list of numbers.
function select_ci(v, i, l=true)
Select specified element from list or return a default.
module align_al(a=z_axis_ci, r=z_axis3d_ul, rp=0, ar=0, to=origin3d, ro=zero3d)
Align an objects Cartesian axis to reference line or vector.
Definition: align.scad:276
module align_ll(l=z_axis3d_ul, r=z_axis3d_ul, lp=0, rp=0, ar=0, to=origin3d, ro=zero3d)
Align a line or vector to a reference line or vector.
Definition: align.scad:208
module orient_ll(l=z_axis3d_ul, r=z_axis3d_ul, ar=0)
Orient a line or vector to a reference line or vector.
Definition: align.scad:164