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