SOFA API  7352f41a
Open source framework for multi-physics simuation
qglviewer::Constraint Class Reference

#include <QGLViewer/constraint.h>

An interface class for Frame constraints. More...

Inheritance diagram for qglviewer::Constraint:

Detailed Description

An interface class for Frame constraints.

This class defines the interface for the Constraints that can be applied to a Frame to limit its motion. Use Frame::setConstraint() to associate a Constraint to a Frame (default is a nullptr Frame::constraint()).

How does it work ?

The Constraint acts as a filter on the translation and rotation Frame increments. constrainTranslation() and constrainRotation() should be overloaded to specify the constraint behavior: the desired displacement is given as a parameter that can optionally be modified.

Here is how the Frame::translate() and Frame::rotate() methods use the Constraint:

{
if (constraint())
constraint()->constrainTranslation(T, this);
t += T;
}
Frame::rotate(Quaternion& Q)
{
if (constraint())
constraint()->constrainRotation(Q, this);
q *= Q;
}
void translate(Vec &t)
Same as translate(const Vec&) but t may be modified to satisfy the translation constraint().
Definition: frame.cpp:327
void rotate(Quaternion &q)
Same as rotate(const Quaternion&) but q may be modified to satisfy the rotation constraint().
Definition: frame.cpp:366

The default behavior of constrainTranslation() and constrainRotation() is empty (meaning no filtering).

The Frame which uses the Constraint is passed as a parameter to the constrainTranslation() and constrainRotation() methods, so that they can have access to its current state (mainly Frame::position() and Frame::orientation()). It is not const for versatility reasons, but directly modifying it should be avoided.

Attention
Frame::setTranslation(), Frame::setRotation() and similar methods will actually indeed set the frame position and orientation, without taking the constraint into account. Use the WithConstraint versions of these methods to enforce the Constraint.

Implemented Constraints

Classical axial and plane Constraints are provided for convenience: see the LocalConstraint, WorldConstraint and CameraConstraint classes' documentations.

Try the constrainedFrame and constrainedCamera examples for an illustration.

Creating new Constraints

The implementation of a new Constraint class simply consists in overloading the filtering methods:

// This Constraint enforces that the Frame cannot have a negative z world
coordinate. class myConstraint : public Constraint
{
public:
virtual void constrainTranslation(Vec& t, Frame * const fr)
{
// Express t in the world coordinate system.
const Vec tWorld = fr->inverseTransformOf(t);
if (fr->position().z + tWorld.z < 0.0) // check the new fr z coordinate
t.z = fr->transformOf(-fr->position().z); // t.z is clamped so that
next z position is 0.0
}
};
virtual void constrainTranslation(Vec &translation, Frame *const frame)
Filters the translation applied to the frame.
Definition: constraint.h:138

Note that the translation (resp. rotation) parameter passed to constrainTranslation() (resp. constrainRotation()) is expressed in the local Frame coordinate system. Here, we use the Frame::transformOf() and Frame::inverseTransformOf() method to convert it to and from the world coordinate system.

Combined constraints can easily be achieved by creating a new class that applies the different constraint filters:

myConstraint::constrainTranslation(Vec& v, Frame* const fr)
{
constraint1->constrainTranslation(v, fr);
constraint2->constrainTranslation(v, fr);
// and so on, with possible branches, tests, loops...
}

Public Member Functions

virtual ~Constraint ()
 Virtual destructor. More...
 
virtual void constrainTranslation (Vec &translation, Frame *const frame)
 Filters the translation applied to the frame. More...
 
virtual void constrainRotation (Quaternion &rotation, Frame *const frame)
 Filters the rotation applied to the frame. More...
 

Constructor details

◆ ~Constraint()

virtual qglviewer::Constraint::~Constraint ( )
inlinevirtual

Virtual destructor.

Empty.

Function details

◆ constrainRotation()

virtual void qglviewer::Constraint::constrainRotation ( Quaternion rotation,
Frame *const  frame 
)
inlinevirtual

Filters the rotation applied to the frame.

This default implementation is empty (no filtering).

Overload this method in your own Constraint class to define a new rotation constraint. See constrainTranslation() for details.

Use Frame::inverseTransformOf() on the rotation Quaternion::axis() to express rotation in the world coordinate system if needed.

Reimplemented in qglviewer::CameraConstraint, qglviewer::WorldConstraint, qglviewer::LocalConstraint, and qglviewer::AxisPlaneConstraint.

◆ constrainTranslation()

virtual void qglviewer::Constraint::constrainTranslation ( Vec translation,
Frame *const  frame 
)
inlinevirtual

Filters the translation applied to the frame.

This default implementation is empty (no filtering).

Overload this method in your own Constraint class to define a new translation constraint. frame is the Frame to which is applied the translation. It is not defined const, but you should refrain from directly changing its value in the constraint. Use its Frame::position() and update the translation accordingly instead.

translation is expressed in local frame coordinate system. Use Frame::inverseTransformOf() to express it in the world coordinate system if needed.

Reimplemented in qglviewer::CameraConstraint, qglviewer::WorldConstraint, qglviewer::LocalConstraint, and qglviewer::AxisPlaneConstraint.