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