omdl  v0.6.1
OpenSCAD Mechanical Design Library
units_angle.scad
Go to the documentation of this file.
1 //! Angle units and conversions.
2 /***************************************************************************//**
3  \file units_angle.scad
4  \author Roy Allen Sutton
5  \date 2015-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 units units_angle
31 *******************************************************************************/
32 
33 include <../constants.scad>;
34 
35 //----------------------------------------------------------------------------//
36 /***************************************************************************//**
37  \addtogroup units
38  @{
39 
40  \defgroup units_angle Angles
41  \brief Angle units and conversions.
42 
43  \details
44 
45  These functions allow for angles to be specified with units.
46  Angles specified with units are independent of (\ref base_unit_angle).
47  There are also unit conversion functions for converting from one unit
48  to another.
49 
50  The table below enumerates the supported units.
51 
52  units id | description | type |
53  :---------:|:----------------------:|:---------------:|
54  r | radian | decimal |
55  d | degree | decimal |
56  dms | degree, minute, second | decimal-list-3 |
57 
58  \b Example
59 
60  \dontinclude units_angle_example.scad
61  \skip include
62  \until to="dms");
63 
64  \b Result (base_angle_length = \b r): \include units_angle_example_r.log
65  \b Result (base_angle_length = \b d): \include units_angle_example_d.log
66  \b Result (base_angle_length = \b dms): \include units_angle_example_dms.log
67 
68  @{
69 *******************************************************************************/
70 //----------------------------------------------------------------------------//
71 
72 //! <string> The base units for angle measurements.
74 
75 //! Return the name of an angle unit identifier.
76 /***************************************************************************//**
77  \param u <string> An angle unit identifier.
78 
79  \returns <string> The units name for the given angle unit identifier.
80  Returns \b undef for identifiers that are not defined.
81 *******************************************************************************/
82 function unit_angle_name
83 (
84  u = base_unit_angle
85 ) = u == "r" ? "radian"
86  : u == "d" ? "degree"
87  : u == "dms" ? "degree, minute, second"
88  : undef;
89 
90 //! Convert an angle from degrees to other units.
91 /***************************************************************************//**
92  \param a <decimal|decimal-list-3> An angle to convert.
93  \param to <string> The units to which the angle should be converted.
94 
95  \returns <decimal|decimal-list-3> The conversion result.
96  Returns \b undef for identifiers that are not defined.
97 
98  \private
99 *******************************************************************************/
100 function unit_angle_d_to
101 (
102  a,
103  to
104 ) = to == "r" ? (a * tau / 360)
105  : to == "d" ? (a)
106  : to == "dms" ? ([
107  floor(a),
108  floor((a - floor(a)) * 60),
109  (a - floor(a) - floor((a - floor(a)) * 60) / 60) * 3600
110  ])
111  : undef;
112 
113 //! Convert an angle from some units to degrees.
114 /***************************************************************************//**
115  \param a <decimal|decimal-list-3> An angle to convert.
116  \param from <string> The units of the angle to be converted.
117 
118  \returns <decimal|decimal-list-3> The conversion result.
119  Returns \b undef for identifiers that are not defined.
120  \private
121 *******************************************************************************/
122 function unit_angle_to_d
123 (
124  a,
125  from
126 ) = from == "r" ? (a * 360 / tau)
127  : from == "d" ? (a)
128  : from == "dms" ? (a[0] + a[1]/60 + a[2]/3600)
129  : undef;
130 
131 //! Convert an angle from some units to another.
132 /***************************************************************************//**
133  \param a <decimal|decimal-list-3> An angle to convert.
134  \param from <string> The units of the angle to be converted.
135  \param to <string> A units to which the angle should be converted.
136 
137  \returns <decimal|decimal-list-3> The conversion result.
138  Returns \b undef for identifiers that are not defined.
139 *******************************************************************************/
140 function convert_angle
141 (
142  a,
143  from = base_unit_angle,
144  to = base_unit_angle
145 ) = unit_angle_d_to( unit_angle_to_d( a, from ), to );
146 
147 //! @}
148 //! @}
149 
150 //----------------------------------------------------------------------------//
151 // openscad-amu auxiliary scripts
152 //----------------------------------------------------------------------------//
153 
154 /*
155 BEGIN_SCOPE example;
156  BEGIN_OPENSCAD;
157  include <units/units_angle.scad>;
158 
159  base_unit_angle = "d";
160 
161  // get base unit name
162  un = unit_angle_name();
163 
164  // absolute angle measurements in base unit.
165  c1 = convert_angle(pi/6, "r");
166  c2 = convert_angle(pi/4, "r");
167  c3 = convert_angle(180, "d");
168  c4 = convert_angle([30, 15, 50], "dms");
169 
170  // convert between units.
171  c5 = convert_angle([30, 15, 50], from="dms", to="r");
172  c6 = convert_angle(0.528205, from="r", to="dms");
173 
174  echo( un=un );
175  echo( c1=c1 );
176  echo( c2=c2 );
177  echo( c3=c3 );
178  echo( c4=c4 );
179  echo( c5=c5 );
180  echo( c6=c6 );
181  END_OPENSCAD;
182 
183  BEGIN_MFSCRIPT;
184  include --path "${INCLUDE_PATH}" {config_base,config_csg}.mfs;
185 
186  defines name "units" define "base_unit_angle" strings "r d dms";
187  variables add_opts_combine "units";
188 
189  include --path "${INCLUDE_PATH}" script_std.mfs;
190  END_MFSCRIPT;
191 END_SCOPE;
192 */
193 
194 //----------------------------------------------------------------------------//
195 // end of file
196 //----------------------------------------------------------------------------//
tau
The ratio of a circle's circumference to its radius.
Definition: constants.scad:51
base_unit_angle
The base units for angle measurements.
function unit_angle_name(u=base_unit_angle)
Return the name of an angle unit identifier.
function convert_angle(a, from=base_unit_angle, to=base_unit_angle)
Convert an angle from some units to another.