1 package org.opentrafficsim.core.math;
2
3 import java.io.Serializable;
4 import java.util.Locale;
5
6 import org.djunits.unit.AccelerationUnit;
7 import org.djunits.unit.DirectionUnit;
8 import org.djunits.value.ValueRuntimeException;
9 import org.djunits.value.vdouble.scalar.Acceleration;
10 import org.djunits.value.vdouble.scalar.Direction;
11 import org.djunits.value.vdouble.vector.AccelerationVector;
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://tudelft.nl/staff/p.knoppers-1">Peter Knoppers</a>
29 */
30 public class Acceleration3d implements Serializable
31 {
32 /** */
33 private static final long serialVersionUID = 20150000L;
34
35 /** The acceleration in 3D (XYZ coded). */
36 private final AccelerationVector acceleration;
37
38 /**
39 * Construct a new Acceleration3d from vector of strongly typed Cartesian coordinates.
40 * @param acceleration AccelerationVector; the accelerations in 3D (YPR coded)
41 * @throws ValueRuntimeException in case the vector does not have exactly three elements
42 */
43 public Acceleration3d(final AccelerationVector acceleration) throws ValueRuntimeException
44 {
45 if (acceleration.size() != 3)
46 {
47 throw new ValueRuntimeException("Size of an RPY-acceleration vector should be exactly 3. Got: " + acceleration);
48 }
49 this.acceleration = acceleration;
50 }
51
52 /**
53 * Construct a new Acceleration3d from three strongly typed Cartesian coordinates.
54 * @param x Acceleration; the acceleration in the x-direction
55 * @param y Acceleration; the acceleration in the y-direction
56 * @param z Acceleration; the acceleration in the z-direction
57 * @throws ValueRuntimeException in case the units are incorrect
58 */
59 public Acceleration3d(final Acceleration x, final Acceleration y, final Acceleration z) throws ValueRuntimeException
60 {
61 this.acceleration = new AccelerationVector(new Acceleration[] {x, y, z}, AccelerationUnit.SI);
62 }
63
64 /**
65 * Construct a new Acceleration3d from three double Cartesian coordinates and a acceleration unit.
66 * @param x double; the acceleration in the x-direction
67 * @param y double; the acceleration in the y-direction
68 * @param z double; the acceleration in the z-direction
69 * @param unit AccelerationUnit; the unit of the xyz parameters
70 * @throws ValueRuntimeException in case the units are incorrect
71 */
72 public Acceleration3d(final double x, final double y, final double z, final AccelerationUnit unit)
73 throws ValueRuntimeException
74 {
75 this.acceleration = new AccelerationVector(new double[] {x, y, z}, AccelerationUnit.SI);
76 }
77
78 /**
79 * Construct a new Acceleration3d from a strongly typed acceleration and polar coordinates.
80 * @param acceleration Acceleration; the acceleration in the direction of the angle along the vector
81 * @param theta Direction; the angle from the z direction
82 * @param phi Direction; the projected angle in the xy-plane from the x direction
83 * @throws ValueRuntimeException in case the vector does not have exactly three elements
84 */
85 public Acceleration3d(final Acceleration acceleration, final Direction theta, final Direction phi)
86 throws ValueRuntimeException
87 {
88 double[] xyz = Scalar3d.polarToCartesian(acceleration.getInUnit(), theta.si, phi.si);
89 this.acceleration = new AccelerationVector(xyz, acceleration.getDisplayUnit());
90 }
91
92 /**
93 * Retrieve the x-component of this Acceleration3d.
94 * @return the acceleration in the x-direction.
95 */
96 public final Acceleration getX()
97 {
98 try
99 {
100 return this.acceleration.get(0);
101 }
102 catch (ValueRuntimeException exception)
103 {
104 // should be impossible as we constructed the vector always with three elements
105 throw new RuntimeException(
106 "getX() gave an exception; apparently vector " + this.acceleration + " was not constructed right",
107 exception);
108 }
109 }
110
111 /**
112 * Retrieve the y-component of this Acceleration3d.
113 * @return the acceleration in the y-direction.
114 */
115 public final Acceleration getY()
116 {
117 try
118 {
119 return this.acceleration.get(1);
120 }
121 catch (ValueRuntimeException exception)
122 {
123 // should be impossible as we constructed the vector always with three elements
124 throw new RuntimeException(
125 "getY() gave an exception; apparently vector " + this.acceleration + " was not constructed right",
126 exception);
127 }
128 }
129
130 /**
131 * Retrieve the z-component of this Acceleration3d.
132 * @return the acceleration in the z-direction.
133 */
134 public final Acceleration getZ()
135 {
136 try
137 {
138 return this.acceleration.get(2);
139 }
140 catch (ValueRuntimeException exception)
141 {
142 // should be impossible as we constructed the vector always with three elements
143 throw new RuntimeException(
144 "getZ() gave an exception; apparently vector " + this.acceleration + " was not constructed right",
145 exception);
146 }
147 }
148
149 /**
150 * Retrieve the theta of this Acceleration3d.
151 * @return the angle of direction perpendicular to the xy-plane
152 */
153 public final Direction getTheta()
154 {
155 return Scalar3d.cartesianToTheta(getX().si, getY().si, getZ().si);
156 }
157
158 /**
159 * Retrieve the phi of this Acceleration3d.
160 * @return the projected angle of direction in the xy-plane
161 */
162 public final Direction getPhi()
163 {
164 return Scalar3d.cartesianToPhi(getX().si, getY().si);
165 }
166
167 /**
168 * Retrieve the norm of this Acceleration3d.
169 * @return the combined acceleration in the direction of the angle
170 */
171 public final Acceleration getAcceleration()
172 {
173 return new Acceleration(Scalar3d.cartesianToRadius(getX().si, getY().si, getZ().si), AccelerationUnit.SI);
174 }
175
176 /** {@inheritDoc} */
177 @Override
178 public final String toString()
179 {
180 return String.format(Locale.US, "Acceleration3d %s (%s, theta %s, phi %s)", this.acceleration, getAcceleration(),
181 new Direction(getTheta().getInUnit(DirectionUnit.EAST_DEGREE), DirectionUnit.EAST_DEGREE),
182 new Direction(getPhi().getInUnit(DirectionUnit.EAST_DEGREE), DirectionUnit.EAST_DEGREE));
183 }
184
185 }