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/util/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* refFrame);
        bool settingAsReferenceFrameWillCreateALoop(const Frame* const frame) const;


        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:
        // Position and orientation
        vec3 t_;    
        quat q_;    
 
        // Constraints
        Constraint *constraint_;    
 
        // Frame composition
        const Frame *referenceFrame_;   
 
    public:
        Signal<> modified;  
    };
 
}
 
#endif // EASY3D_RENDERER_FRAME_H