001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017
018package org.apache.commons.math3.geometry.euclidean.threed;
019
020/**
021 * This class is a utility representing a rotation order specification
022 * for Cardan or Euler angles specification.
023 *
024 * This class cannot be instanciated by the user. He can only use one
025 * of the twelve predefined supported orders as an argument to either
026 * the {@link Rotation#Rotation(RotationOrder,double,double,double)}
027 * constructor or the {@link Rotation#getAngles} method.
028 *
029 * @since 1.2
030 */
031public final class RotationOrder {
032
033    /** Set of Cardan angles.
034     * this ordered set of rotations is around X, then around Y, then
035     * around Z
036     */
037    public static final RotationOrder XYZ =
038      new RotationOrder("XYZ", Vector3D.PLUS_I, Vector3D.PLUS_J, Vector3D.PLUS_K);
039
040    /** Set of Cardan angles.
041     * this ordered set of rotations is around X, then around Z, then
042     * around Y
043     */
044    public static final RotationOrder XZY =
045      new RotationOrder("XZY", Vector3D.PLUS_I, Vector3D.PLUS_K, Vector3D.PLUS_J);
046
047    /** Set of Cardan angles.
048     * this ordered set of rotations is around Y, then around X, then
049     * around Z
050     */
051    public static final RotationOrder YXZ =
052      new RotationOrder("YXZ", Vector3D.PLUS_J, Vector3D.PLUS_I, Vector3D.PLUS_K);
053
054    /** Set of Cardan angles.
055     * this ordered set of rotations is around Y, then around Z, then
056     * around X
057     */
058    public static final RotationOrder YZX =
059      new RotationOrder("YZX", Vector3D.PLUS_J, Vector3D.PLUS_K, Vector3D.PLUS_I);
060
061    /** Set of Cardan angles.
062     * this ordered set of rotations is around Z, then around X, then
063     * around Y
064     */
065    public static final RotationOrder ZXY =
066      new RotationOrder("ZXY", Vector3D.PLUS_K, Vector3D.PLUS_I, Vector3D.PLUS_J);
067
068    /** Set of Cardan angles.
069     * this ordered set of rotations is around Z, then around Y, then
070     * around X
071     */
072    public static final RotationOrder ZYX =
073      new RotationOrder("ZYX", Vector3D.PLUS_K, Vector3D.PLUS_J, Vector3D.PLUS_I);
074
075    /** Set of Euler angles.
076     * this ordered set of rotations is around X, then around Y, then
077     * around X
078     */
079    public static final RotationOrder XYX =
080      new RotationOrder("XYX", Vector3D.PLUS_I, Vector3D.PLUS_J, Vector3D.PLUS_I);
081
082    /** Set of Euler angles.
083     * this ordered set of rotations is around X, then around Z, then
084     * around X
085     */
086    public static final RotationOrder XZX =
087      new RotationOrder("XZX", Vector3D.PLUS_I, Vector3D.PLUS_K, Vector3D.PLUS_I);
088
089    /** Set of Euler angles.
090     * this ordered set of rotations is around Y, then around X, then
091     * around Y
092     */
093    public static final RotationOrder YXY =
094      new RotationOrder("YXY", Vector3D.PLUS_J, Vector3D.PLUS_I, Vector3D.PLUS_J);
095
096    /** Set of Euler angles.
097     * this ordered set of rotations is around Y, then around Z, then
098     * around Y
099     */
100    public static final RotationOrder YZY =
101      new RotationOrder("YZY", Vector3D.PLUS_J, Vector3D.PLUS_K, Vector3D.PLUS_J);
102
103    /** Set of Euler angles.
104     * this ordered set of rotations is around Z, then around X, then
105     * around Z
106     */
107    public static final RotationOrder ZXZ =
108      new RotationOrder("ZXZ", Vector3D.PLUS_K, Vector3D.PLUS_I, Vector3D.PLUS_K);
109
110    /** Set of Euler angles.
111     * this ordered set of rotations is around Z, then around Y, then
112     * around Z
113     */
114    public static final RotationOrder ZYZ =
115      new RotationOrder("ZYZ", Vector3D.PLUS_K, Vector3D.PLUS_J, Vector3D.PLUS_K);
116
117    /** Name of the rotations order. */
118    private final String name;
119
120    /** Axis of the first rotation. */
121    private final Vector3D a1;
122
123    /** Axis of the second rotation. */
124    private final Vector3D a2;
125
126    /** Axis of the third rotation. */
127    private final Vector3D a3;
128
129    /** Private constructor.
130     * This is a utility class that cannot be instantiated by the user,
131     * so its only constructor is private.
132     * @param name name of the rotation order
133     * @param a1 axis of the first rotation
134     * @param a2 axis of the second rotation
135     * @param a3 axis of the third rotation
136     */
137    private RotationOrder(final String name,
138                          final Vector3D a1, final Vector3D a2, final Vector3D a3) {
139        this.name = name;
140        this.a1   = a1;
141        this.a2   = a2;
142        this.a3   = a3;
143    }
144
145    /** Get a string representation of the instance.
146     * @return a string representation of the instance (in fact, its name)
147     */
148    @Override
149    public String toString() {
150        return name;
151    }
152
153    /** Get the axis of the first rotation.
154     * @return axis of the first rotation
155     */
156    public Vector3D getA1() {
157        return a1;
158    }
159
160    /** Get the axis of the second rotation.
161     * @return axis of the second rotation
162     */
163    public Vector3D getA2() {
164        return a2;
165    }
166
167    /** Get the axis of the second rotation.
168     * @return axis of the second rotation
169     */
170    public Vector3D getA3() {
171        return a3;
172    }
173
174}