1 package org.opentrafficsim.core.math;
2
3 import java.util.Locale;
4
5 import org.djunits.unit.AccelerationUnit;
6 import org.djunits.unit.DirectionUnit;
7 import org.djunits.value.ValueRuntimeException;
8 import org.djunits.value.vdouble.scalar.Acceleration;
9 import org.djunits.value.vdouble.scalar.Direction;
10 import org.djunits.value.vdouble.vector.AccelerationVector;
11 import org.opentrafficsim.base.OtsRuntimeException;
12
13 /**
14 * A 3D acceleration vector, decomposed in X, Y, and Z-acceleration with easy conversion from and to a spherical coordinate
15 * system. <br>
16 * <a href="https://en.wikipedia.org/wiki/Spherical_coordinate_system">Physicists and mathematicians <strong>do not</strong>
17 * agree on the meaning of theta and phi.</a> In this class the convention in the physics domain is used:
18 * <ul>
19 * <li>theta is the angle from the z direction.</li>
20 * <li>phi is the projected angle in the xy-plane from the x direction.</li>
21 * </ul>
22 * N.B. In the geography domain yet another convention is used. <br>
23 * <p>
24 * Copyright (c) 2013-2024 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved. <br>
25 * BSD-style license. See <a href="https://opentrafficsim.org/docs/license.html">OpenTrafficSim License</a>.
26 * </p>
27 * @author <a href="https://github.com/averbraeck">Alexander Verbraeck</a>
28 * @author <a href="https://github.com/peter-knoppers">Peter Knoppers</a>
29 */
30 public class Acceleration3d
31 {
32 /** The acceleration in 3D (XYZ coded). */
33 private final AccelerationVector acceleration;
34
35 /**
36 * Construct a new Acceleration3d from vector of strongly typed Cartesian coordinates.
37 * @param acceleration the accelerations in 3D (YPR coded)
38 * @throws ValueRuntimeException in case the vector does not have exactly three elements
39 */
40 public Acceleration3d(final AccelerationVector acceleration) throws ValueRuntimeException
41 {
42 if (acceleration.size() != 3)
43 {
44 throw new ValueRuntimeException("Size of an RPY-acceleration vector should be exactly 3. Got: " + acceleration);
45 }
46 this.acceleration = acceleration;
47 }
48
49 /**
50 * Construct a new Acceleration3d from three strongly typed Cartesian coordinates.
51 * @param x the acceleration in the x-direction
52 * @param y the acceleration in the y-direction
53 * @param z the acceleration in the z-direction
54 * @throws ValueRuntimeException in case the units are incorrect
55 */
56 public Acceleration3d(final Acceleration x, final Acceleration y, final Acceleration z) throws ValueRuntimeException
57 {
58 this.acceleration = new AccelerationVector(new Acceleration[] {x, y, z}, AccelerationUnit.SI);
59 }
60
61 /**
62 * Construct a new Acceleration3d from three double Cartesian coordinates and a acceleration unit.
63 * @param x the acceleration in the x-direction
64 * @param y the acceleration in the y-direction
65 * @param z the acceleration in the z-direction
66 * @param unit the unit of the xyz parameters
67 * @throws ValueRuntimeException in case the units are incorrect
68 */
69 public Acceleration3d(final double x, final double y, final double z, final AccelerationUnit unit)
70 throws ValueRuntimeException
71 {
72 this.acceleration = new AccelerationVector(new double[] {x, y, z}, AccelerationUnit.SI);
73 }
74
75 /**
76 * Construct a new Acceleration3d from a strongly typed acceleration and polar coordinates.
77 * @param acceleration the acceleration in the direction of the angle along the vector
78 * @param theta the angle from the z direction
79 * @param phi the projected angle in the xy-plane from the x direction
80 * @throws ValueRuntimeException in case the vector does not have exactly three elements
81 */
82 public Acceleration3d(final Acceleration acceleration, final Direction theta, final Direction phi)
83 throws ValueRuntimeException
84 {
85 double[] xyz = Scalar3d.polarToCartesian(acceleration.getInUnit(), theta.si, phi.si);
86 this.acceleration = new AccelerationVector(xyz, acceleration.getDisplayUnit());
87 }
88
89 /**
90 * Retrieve the x-component of this Acceleration3d.
91 * @return the acceleration in the x-direction.
92 */
93 public final Acceleration getX()
94 {
95 try
96 {
97 return this.acceleration.get(0);
98 }
99 catch (ValueRuntimeException exception)
100 {
101 // should be impossible as we constructed the vector always with three elements
102 throw new OtsRuntimeException(
103 "getX() gave an exception; apparently vector " + this.acceleration + " was not constructed right",
104 exception);
105 }
106 }
107
108 /**
109 * Retrieve the y-component of this Acceleration3d.
110 * @return the acceleration in the y-direction.
111 */
112 public final Acceleration getY()
113 {
114 try
115 {
116 return this.acceleration.get(1);
117 }
118 catch (ValueRuntimeException exception)
119 {
120 // should be impossible as we constructed the vector always with three elements
121 throw new OtsRuntimeException(
122 "getY() gave an exception; apparently vector " + this.acceleration + " was not constructed right",
123 exception);
124 }
125 }
126
127 /**
128 * Retrieve the z-component of this Acceleration3d.
129 * @return the acceleration in the z-direction.
130 */
131 public final Acceleration getZ()
132 {
133 try
134 {
135 return this.acceleration.get(2);
136 }
137 catch (ValueRuntimeException exception)
138 {
139 // should be impossible as we constructed the vector always with three elements
140 throw new OtsRuntimeException(
141 "getZ() gave an exception; apparently vector " + this.acceleration + " was not constructed right",
142 exception);
143 }
144 }
145
146 /**
147 * Retrieve the theta of this Acceleration3d.
148 * @return the angle of direction perpendicular to the xy-plane
149 */
150 public final Direction getTheta()
151 {
152 return Scalar3d.cartesianToTheta(getX().si, getY().si, getZ().si);
153 }
154
155 /**
156 * Retrieve the phi of this Acceleration3d.
157 * @return the projected angle of direction in the xy-plane
158 */
159 public final Direction getPhi()
160 {
161 return Scalar3d.cartesianToPhi(getX().si, getY().si);
162 }
163
164 /**
165 * Retrieve the norm of this Acceleration3d.
166 * @return the combined acceleration in the direction of the angle
167 */
168 public final Acceleration getAcceleration()
169 {
170 return new Acceleration(Scalar3d.cartesianToRadius(getX().si, getY().si, getZ().si), AccelerationUnit.SI);
171 }
172
173 @Override
174 public final String toString()
175 {
176 return String.format(Locale.US, "Acceleration3d %s (%s, theta %s, phi %s)", this.acceleration, getAcceleration(),
177 new Direction(getTheta().getInUnit(DirectionUnit.EAST_DEGREE), DirectionUnit.EAST_DEGREE),
178 new Direction(getPhi().getInUnit(DirectionUnit.EAST_DEGREE), DirectionUnit.EAST_DEGREE));
179 }
180
181 }