001/*
002*   Rotation -- Represents an attitude transformation between two different frames.
003*
004*   Copyright (C) 2009-2025, by Joseph A. Huwaldt. All rights reserved.
005*   
006*   This library is free software; you can redistribute it and/or
007*   modify it under the terms of the GNU Lesser General Public
008*   License as published by the Free Software Foundation; either
009*   version 2 of the License, or (at your option) any later version.
010*   
011*   This library is distributed in the hope that it will be useful,
012*   but WITHOUT ANY WARRANTY; without even the implied warranty of
013*   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014*   Lesser General Public License for more details.
015*
016*   You should have received a copy of the GNU Lesser General Public License
017*   along with this program; if not, write to the Free Software
018*   Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
019*   Or visit:  http://www.gnu.org/licenses/lgpl.html
020 */
021package jahuwaldt.js.param;
022
023import javax.measure.quantity.Quantity;
024import javolution.lang.Realtime;
025import javolution.lang.ValueType;
026
027/**
028 * <p>
029 * This class represents a relative orientation (attitude or rotation transformation)
030 * between two different reference frames; B wrt A or BA. It can be used to transform
031 * coordinates in reference frame A to reference frame B (A2B).</p>
032 *
033 * <p>
034 * Modified by: Joseph A. Huwaldt   </p>
035 *
036 * @author Joseph A. Huwaldt Date: October 22, 2009
037 * @version February 23, 2025
038 */
039@SuppressWarnings("rawtypes")
040public interface Rotation<T extends Rotation<?>> extends ValueType, Realtime {
041
042    /**
043     * A Rotation object that represents no relative change in orientation.
044     */
045    public static final Rotation IDENTITY = DCMatrix.IDENT;
046
047    /**
048     * Transforms a 3D vector from frame A to B using this attitude transformation.
049     *
050     * @param v   the vector expressed in frame A.
051     * @param <Q> The Quantity or unit type for this parameter.
052     * @return the vector expressed in frame B.
053     */
054    public <Q extends Quantity> Vector3D<Q> transform(Coordinate3D<Q> v);
055
056    /**
057     * Returns the spatial inverse of this transformation: AB rather than BA.
058     *
059     * @return <code>this'</code>
060     */
061    public T transpose();
062
063    /**
064     * Returns the product of this attitude transformation and another. If this attitude
065     * transform is BA and that is AC then the returned value is:
066     *  <code>BC = BA · AC (or C2B = A2B  · C2A)</code>.
067     *
068     * @param that the attitude transform multiplier.
069     * @return <code>this · that</code>
070     */
071    public T times(Rotation<?> that);
072
073    /**
074     * Returns a direction cosine transformation matrix from this attitude transformation.
075     *
076     * @return a direction cosine matrix that converts from frame A to B.
077     * @see <a href="http://en.wikipedia.org/wiki/Rotation_representation_(mathematics)">
078     * Wikipedia: Rotation representation (mathematics)</a>
079     */
080    public DCMatrix toDCM();
081
082    /**
083     * Returns a quaternion representing this attitude transformation.
084     *
085     * @return a quaternion that converts from frame A to B.
086     * @see <a href="http://en.wikipedia.org/wiki/Quaternion"> Wikipedia: Quaternion</a>
087     */
088    public Quaternion toQuaternion();
089
090    /**
091     * Returns an independent copy of this attitude transform.
092     */
093    @Override
094    public T copy();
095
096}