frame.h

/********************************************************************
 * Copyright (C) 2015 Liangliang Nan <liangliang.nan@gmail.com>
 * https://3d.bk.tudelft.nl/liangliang/
 *
 * This file is part of Easy3D. If it is useful in your research/work,
 * I would be grateful if you show your appreciation by citing it:
 * ------------------------------------------------------------------
 *      Liangliang Nan.
 *      Easy3D: a lightweight, easy-to-use, and efficient C++ library
 *      for processing and rendering 3D data.
 *      Journal of Open Source Software, 6(64), 3255, 2021.
 * ------------------------------------------------------------------
 *
 * Easy3D is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License Version 3
 * as published by the Free Software Foundation.
 *
 * Easy3D is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program. If not, see <http://www.gnu.org/licenses/>.
 ********************************************************************/
 
#ifndef EASY3D_RENDERER_FRAME_H
#define EASY3D_RENDERER_FRAME_H
 
#include <easy3d/core/types.h>
#include <easy3d/core/signal.h>
#include <easy3d/renderer/constraint.h>
 
 
namespace easy3d {
 
 
    class Frame {
    public:
        Frame();
        virtual ~Frame();
 
        Frame(const Frame &frame);
        Frame &operator=(const Frame &frame);
 
    public:
        Frame(const vec3 &position, const quat &orientation);
 
        void setPosition(const vec3 &position);
 
        void setPositionWithConstraint(vec3 &position);
 
        void setOrientation(const quat &orientation);
 
        void setOrientationWithConstraint(quat &orientation);
 
        void setPositionAndOrientation(const vec3 &position,
                                       const quat &orientation);
 
        void setPositionAndOrientationWithConstraint(vec3 &position,
                                                     quat &orientation);
 
        vec3 position() const;
 
        quat orientation() const;
 
 
    public:
        void setTranslation(const vec3 &translation) {
            t_ = translation;
            modified.send();
        }
 
        void setTranslationWithConstraint(vec3 &translation);
 
        void setRotation(const quat &rotation) {
            q_ = rotation;
            modified.send();
        }
 
        void setRotationWithConstraint(quat &rotation);
 
        void setTranslationAndRotation(const vec3 &translation, const quat &rotation);
 
        void setTranslationAndRotationWithConstraint(vec3 &translation, quat &rotation);
 
        vec3 translation() const { return t_; }
        quat rotation() const { return q_; }
 
    public:
        const Frame *referenceFrame() const { return referenceFrame_; }
 
        void setReferenceFrame(const Frame *const refFrame);
 
        bool settingAsReferenceFrameWillCreateALoop(const Frame *const frame);
 
        void translate(vec3 &t);
 
        void translate(const vec3 &t);
 
        void rotate(quat &q);
 
        void rotate(const quat &q);
 
        void rotateAroundPoint(quat &rotation, const vec3 &point);
 
        void rotateAroundPoint(const quat &rotation, const vec3 &point);
 
        void alignWithFrame(const Frame *const frame, bool move = false,
                            float threshold = 0.0f);
 
        void projectOnLine(const vec3 &origin, const vec3 &direction);
 
        vec3 coordinatesOf(const vec3 &src) const;
 
        vec3 inverseCoordinatesOf(const vec3 &src) const;
 
        vec3 localCoordinatesOf(const vec3 &src) const;
 
        vec3 localInverseCoordinatesOf(const vec3 &src) const;
 
        vec3 coordinatesOfIn(const vec3 &src, const Frame *const in) const;
 
        vec3 coordinatesOfFrom(const vec3 &src, const Frame *const from) const;
 
        // A frame is as a new coordinate system, defined with respect to a reference
        // frame (the world coordinate system by default, see the "Composition of
        // frame" section).
 
        // The transformOf() (resp. inverseTransformOf()) functions transform a 3D
        // vector from (resp. to) the world coordinate system. This section defines
        // the 3D vector transformation functions. See the Coordinate system
        // transformation of 3D points above for the transformation of 3D points. The
        // difference between the two sets of functions is simple: for vectors, only
        // the rotational part of the transformations is taken into account, while
        // translation is also considered for 3D points.
 
        // The length of the resulting transformed vector is identical to the one of
        // the source vector for all the described functions.
 
        // When local is prepended to the names of the functions, the functions simply
        // transform from (and to) the reference frame.
 
        // When In (resp. From) is appended to the names, the functions transform from
        // (resp. To) the frame that is given as an argument. The frame does not need
        // to be in the same branch or the hierarchical tree, and can be \c NULL (the
        // world coordinates system).
 
        // Combining any of these functions with its inverse (in any order) leads to
        // the identity.
        vec3 transformOf(const vec3 &src) const;
 
        vec3 inverseTransformOf(const vec3 &src) const;
 
        vec3 localTransformOf(const vec3 &src) const;
 
        vec3 localInverseTransformOf(const vec3 &src) const;
 
        vec3 transformOfIn(const vec3 &src, const Frame *const in) const;
 
        vec3 transformOfFrom(const vec3 &src, const Frame *const from) const;
 
        Constraint *constraint() const { return constraint_; }
 
        void setConstraint(Constraint *const constraint) { constraint_ = constraint; }
 
 
    public:
        mat4 matrix() const;
 
        mat4 worldMatrix() const;
 
        void setFromMatrix(const mat4 &m);
 
 
        Frame inverse() const;
 
        Frame worldInverse() const {
            return Frame(-(orientation().inverse_rotate(position())), orientation().inverse());
        }
 
    private:
        // P o s i t i o n   a n d   o r i e n t a t i o n
        vec3 t_;
        quat q_;
 
        // C o n s t r a i n t s
        Constraint *constraint_;
 
        // F r a m e   c o m p o s i t i o n
        const Frame *referenceFrame_;
 
    public:
        Signal<> modified;
    };
 
}
 
#endif // EASY3D_RENDERER_FRAME_H