omdl  v0.6.1
OpenSCAD Mechanical Design Library
tools_align.scad
Go to the documentation of this file.
1 //! Shape alignment tools.
2 /***************************************************************************//**
3  \file tools_align.scad
4  \author Roy Allen Sutton
5  \date 2017
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  \ingroup tools tools_align
31 *******************************************************************************/
32 
33 include <../math/math-base.scad>;
34 
35 //----------------------------------------------------------------------------//
36 /***************************************************************************//**
37  \addtogroup tools
38  @{
39 
40  \defgroup tools_align Alignment
41  \brief Shape alignment tools.
42  @{
43 *******************************************************************************/
44 //----------------------------------------------------------------------------//
45 
46 //! Orient a line or vector to a reference line or vector.
47 /***************************************************************************//**
48  \param l <line-3d|line-2d> The line or vector to align.
49  \param rl <line-3d|line-2d> The reference line or vector.
50 
51  \param r <decimal> Roll about axis \p rl (in degrees).
52 
53  \details
54 
55  See \ref dt_line for argument specification and conventions.
56 *******************************************************************************/
57 module orient_ll
58 (
59  l = z_axis3d_ul,
60  rl = z_axis3d_ul,
61  r = 0
62 )
63 {
64  ll = get_line2origin(l);
65  lr = get_line2origin(rl);
66 
67  rotate(r, lr)
68  rotate(angle_ll(ll, lr), cross(ll, lr))
69  children();
70 }
71 
72 //! Align a line or vector to a reference line or vector.
73 /***************************************************************************//**
74  \param l <line-3d|line-2d> The line or vector to align.
75  \param rl <line-3d|line-2d> The reference line or vector.
76 
77  \param ap <integer> The line alignment point (see table).
78  \param rp <integer> The reference-line alignment point (see table).
79 
80  \param r <decimal> Roll about axis \p rl (in degrees).
81 
82  \param to <vector-3d|vector-2d> Translation offset about \p rl.
83  \param ro <decimal-list-1:3|decimal> Rotation offset about \p rl
84  (in degrees).
85 
86  \details
87 
88  The specified alignment point for the line \p l will be a translated
89  to the specified alignment point for the reference line \p rl.
90 
91  | ap, rp | alignment point |
92  |:-------:|:----------------------|
93  | 0 | none (no translation) |
94  | 1 | initial |
95  | 2 | median |
96  | 3 | termination |
97  | 4 | initial + termination |
98 
99  See \ref dt_line for argument specification and conventions.
100 *******************************************************************************/
101 module align_ll
102 (
103  l = z_axis3d_ul,
104  rl = z_axis3d_ul,
105  ap = 0,
106  rp = 0,
107  r = 0,
108  to = origin3d,
109  ro = zero3d
110 )
111 {
112  li = dimension_2to3_v(get_line_ip( l));
113  lt = dimension_2to3_v(get_line_tp( l));
114 
115  ri = dimension_2to3_v(get_line_ip(rl));
116  rt = dimension_2to3_v(get_line_tp(rl));
117 
118  ll = [li, lt];
119  lm = mean(ll);
120 
121  lr = [ri, rt];
122  rm = mean(lr);
123 
124  // translate reference
125  translate(ciselect([origin3d, ri, rm, rt, ri+rt, rm], rp))
126 
127  // orient and roll line about reference
128  rotate(r, get_line2origin(lr))
129  rotate(angle_ll(ll, lr), cross_ll(ll, lr))
130 
131  // apply offsets
132  translate(to)
133  rotate(ro)
134 
135  // translate alignment point
136  translate(-ciselect([origin3d, li, lm, lt, li+lt, lm], ap))
137  children();
138 }
139 
140 //! Align a shapes' x, y, or z Cartesian axis to reference line or vector.
141 /***************************************************************************//**
142  \param rl <line-3d|line-2d> The reference line or vector.
143 
144  \param rp <integer> The reference-line alignment point (see table).
145 
146  \param r <decimal> Roll about axis \p rl (in degrees).
147 
148  \param to <vector-3d|vector-2d> Translation offset about \p rl.
149  \param ro <decimal-list-1:3|decimal> Rotation offset about \p rl
150  (in degrees).
151 
152  \param d <integer> The Cartesian axis index to align (0, 1, or 2).
153 
154  \details
155 
156  The origin will be a translated to the specified alignment point
157  for the reference line \p rl.
158 
159  | ap, rp | alignment point |
160  |:-------:|:----------------------|
161  | 0 | none (no translation) |
162  | 1 | initial |
163  | 2 | median |
164  | 3 | termination |
165  | 4 | initial + termination |
166 
167  See \ref dt_line for argument specification and conventions.
168 *******************************************************************************/
169 module align_l
170 (
171  rl = z_axis3d_ul,
172  rp = 0,
173  r = 0,
174  to = origin3d,
175  ro = zero3d,
176  d = z_axis_ci
177 )
178 {
179  ra = ciselect([x_axis3d_ul, y_axis3d_ul, z_axis3d_ul], d);
180 
181  align_ll(ra, rl, 0, rp, r, to, ro)
182  children();
183 }
184 
185 //! @}
186 //! @}
187 
188 //----------------------------------------------------------------------------//
189 // end of file
190 //----------------------------------------------------------------------------//
zero3d
zero3d
A 3d zero vector (a list with three zeros).
Definition: constants.scad:124
cross_ll
function cross_ll(l1, l2)
Compute the cross product of two lines (or vectors) in a Euclidean 3d or 2d-space.
mean
function mean(v)
Compute the mean/average of a list of numbers.
align_l
module align_l(rl=z_axis3d_ul, rp=0, r=0, to=origin3d, ro=zero3d, d=z_axis_ci)
Align a shapes' x, y, or z Cartesian axis to reference line or vector.
Definition: tools_align.scad:170
x_axis3d_ul
x_axis3d_ul
A positively-directed unit line centered on the x-axis in 3d Euclidean space.
Definition: constants.scad:139
orient_ll
module orient_ll(l=z_axis3d_ul, rl=z_axis3d_ul, r=0)
Orient a line or vector to a reference line or vector.
Definition: tools_align.scad:58
ciselect
function ciselect(v, i)
Case-like select a value from a list of ordered value options.
dimension_2to3_v
function dimension_2to3_v(v)
Return 3d vector unchanged or add a zeroed third dimension to 2d vector.
get_line_ip
function get_line_ip(l)
Return the initial point of a Euclidean line (or vector).
z_axis_ci
z_axis_ci
The coordinate axis index for the Euclidean space z-axis.
Definition: constants.scad:103
get_line_tp
function get_line_tp(l)
Return the terminal point of a Euclidean line (or vector).
origin3d
origin3d
The origin point coordinate in 3-dimensional Euclidean space.
Definition: constants.scad:127
angle_ll
function angle_ll(l1, l2)
Compute the angle between two lines (or vectors) in a Euclidean 3d or 2d-space.
y_axis3d_ul
y_axis3d_ul
A positively-directed unit line centered on the y-axis in 3d Euclidean space.
Definition: constants.scad:142
align_ll
module align_ll(l=z_axis3d_ul, rl=z_axis3d_ul, ap=0, rp=0, r=0, to=origin3d, ro=zero3d)
Align a line or vector to a reference line or vector.
Definition: tools_align.scad:102
get_line2origin
function get_line2origin(l)
Shift a Euclidean line (or vector) to the origin.
z_axis3d_ul
z_axis3d_ul
A positively-directed unit line centered on the z-axis in 3d Euclidean space.
Definition: constants.scad:145