DecorativeGeometry.h

Go to the documentation of this file.

#ifndef SimTK_SimTKCOMMON_DECORATIVE_GEOMETRY_H_
#define SimTK_SimTKCOMMON_DECORATIVE_GEOMETRY_H_

/* -------------------------------------------------------------------------- *
 *                      SimTK Core: SimTKcommon                               *
 * -------------------------------------------------------------------------- *
 * This is part of the SimTK Core biosimulation toolkit originating from      *
 * Simbios, the NIH National Center for Physics-Based Simulation of           *
 * Biological Structures at Stanford, funded under the NIH Roadmap for        *
 * Medical Research, grant U54 GM072970. See https://simtk.org.               *
 *                                                                            *
 * Portions copyright (c) 2005-7 Stanford University and the Authors.         *
 * Authors: Michael Sherman                                                   *
 * Contributors: Jack Middleton                                               *
 *                                                                            *
 * Permission is hereby granted, free of charge, to any person obtaining a    *
 * copy of this software and associated documentation files (the "Software"), *
 * to deal in the Software without restriction, including without limitation  *
 * the rights to use, copy, modify, merge, publish, distribute, sublicense,   *
 * and/or sell copies of the Software, and to permit persons to whom the      *
 * Software is furnished to do so, subject to the following conditions:       *
 *                                                                            *
 * The above copyright notice and this permission notice shall be included in *
 * all copies or substantial portions of the Software.                        *
 *                                                                            *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR *
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,   *
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL    *
 * THE AUTHORS, CONTRIBUTORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,    *
 * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR      *
 * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE  *
 * USE OR OTHER DEALINGS IN THE SOFTWARE.                                     *
 * -------------------------------------------------------------------------- */

/* TODO: NEW TEXT -- NOT IMPLEMENTED YET (just thinking out loud)
 *
 * Each kind of Decoration defines a parameterized object, whose appearance
 * is specified once its parameters are known. Parameters will be scalars,
 * points, direction vectors, and transforms. These involve dependencies on
 * a fixed set of reference frames: the ground body frame, the moving body frames,
 * and the screen or viewing frame. The body frames are defined by the System;
 * while the viewing frame is defined by whatever application is communicating
 * to a user. The World frame of the viewer and the Ground frame of the System
 * are the same. At run time a System can always report the configuration of its
 * moving bodies with respect to Ground, and hence these can be placed in the
 * scene with respect to the World frame. A text label, for example, could be tethered
 * to a point on a moving body while defined to remain parallel to the viewing plane.
 *
 * In addition to their geometric representations, Decorations defined here can 
 * state preferences, if any, for a variety of viewing options such as color,
 * drawing style, and transparency. If left unspecified, the viewer will have to
 * determine how to set these options; if specified the viewer may want to use
 * the specified options but can override them if it has good reason to do so.
 * Many different implementations of Decorations are possible. The generic 
 * implementation is defined below as an abstract class; each viewer will use
 * a particular implementation that defines a concrete implementation for each of the virtual
 * methods of the abstraction.
 *
 * There are two Stages associated with a Decoration. When is the Decoration
 * known to exist (including its parameterization), and when are values for its 
 * parameters calculatable. For example, a permanent body-fixed sphere is known
 * to exist a the Topological stage (i.e., as soon as the body exists). Its 
 * configuration in the World frame, however, cannot be computed until we
 * know the body's configuration, that is, Stage::Position.
 */

#include "SimTKcommon/Simmatrix.h"
#include "SimTKcommon/internal/PolygonalMesh.h"

#include <cassert>


namespace SimTK {

class AnalyticGeometry;


// Some common RGB values;
static const Vec3 Black   = Vec3( 0, 0, 0);
static const Vec3 Gray    = Vec3(.5,.5,.5);
static const Vec3 Red     = Vec3( 1, 0, 0);
static const Vec3 Green   = Vec3( 0, 1, 0);
static const Vec3 Blue    = Vec3( 0, 0, 1);
static const Vec3 Yellow  = Vec3( 1, 1, 0);
static const Vec3 Orange  = Vec3( 1,.5, 0);
static const Vec3 Magenta = Vec3( 1, 0, 1);
static const Vec3 Purple  = Vec3(.5, 0,.5);
static const Vec3 Cyan    = Vec3( 0, 1, 1);
static const Vec3 White   = Vec3( 1, 1, 1);

// Drawing representations

class DecorativeGeometryImplementation;

class SimTK_SimTKCOMMON_EXPORT DecorativeGeometry {
public:
    DecorativeGeometry() : rep(0) { }
    ~DecorativeGeometry();
    DecorativeGeometry(const DecorativeGeometry&);
    DecorativeGeometry& operator=(const DecorativeGeometry&);

    // Drawing modes.
    enum Representation {
        DrawPoints    =  1,
        DrawWireframe =  2,
        DrawSurface   =  3,

        DrawDefault   = -1
    };

    DecorativeGeometry(const AnalyticGeometry&);

    DecorativeGeometry& setBodyId(int);

    DecorativeGeometry& setTransform(const Transform& X_BG);

    DecorativeGeometry& setResolution(Real);

    DecorativeGeometry& setScale(Real);

    int getBodyId() const;

    Real getResolution() const;

    const Transform& getTransform() const;

    Real getScale() const;

    DecorativeGeometry& setColor(const Vec3& rgb); // 0-1 for each color

    DecorativeGeometry& setOpacity(Real);          // 0-1; default is 1 (opaque)

    DecorativeGeometry& setLineThickness(Real);

    const Vec3& getColor()      const;
    Real        getOpacity()    const;
    Real        getLineThickness() const;
    
    DecorativeGeometry& setFaceCamera(bool face);
    bool getFaceCamera() const;

    DecorativeGeometry& setRepresentation(const Representation&);

    Representation getRepresentation() const;

    void implementGeometry(DecorativeGeometryImplementation&) const;

    // Bookkeeping below here -- internal use only. Don't look below or you will
    // turn into a pillar of salt.
    bool isOwnerHandle() const;
    bool isEmptyHandle() const;
    explicit DecorativeGeometry(class DecorativeGeometryRep* r) : rep(r) { }
    bool hasRep() const {return rep!=0;}
    const DecorativeGeometryRep& getRep() const {assert(rep); return *rep;}
    DecorativeGeometryRep&       updRep()       {assert(rep); return *rep;}
protected:
    DecorativeGeometryRep* rep;
};

class SimTK_SimTKCOMMON_EXPORT DecorativeLine : public DecorativeGeometry {
public:
    explicit DecorativeLine(const Vec3& p1=Vec3(0), const Vec3& p2=Vec3(1)); // line between p1 and p2

    // Retain the derived type when setting generic geometry options.
    DecorativeLine& setBodyId(int b)          {DecorativeGeometry::setBodyId(b);        return *this;}
    DecorativeLine& setTransform(const Transform& X_BD) {DecorativeGeometry::setTransform(X_BD); return *this;}
    DecorativeLine& setResolution(Real r)     {DecorativeGeometry::setResolution(r);    return *this;}
    DecorativeLine& setScale(Real s)          {DecorativeGeometry::setScale(s);         return *this;}
    DecorativeLine& setColor(const Vec3& rgb) {DecorativeGeometry::setColor(rgb);       return *this;}
    DecorativeLine& setOpacity(Real o)        {DecorativeGeometry::setOpacity(o);       return *this;}
    DecorativeLine& setLineThickness(Real t)  {DecorativeGeometry::setLineThickness(t); return *this;}
    DecorativeLine& setRepresentation(const Representation& r) {
        DecorativeGeometry::setRepresentation(r); return *this;
    }

    // These are specific to lines.
    DecorativeLine& setPoint1(const Vec3& p1);
    DecorativeLine& setPoint2(const Vec3& p2);
    DecorativeLine& setEndpoints(const Vec3& p1, const Vec3& p2);

    const Vec3& getPoint1() const;
    const Vec3& getPoint2() const;

    SimTK_PIMPL_DOWNCAST(DecorativeLine, DecorativeGeometry);
private:
    class DecorativeLineRep& updRep();
    const DecorativeLineRep& getRep() const;
};

class SimTK_SimTKCOMMON_EXPORT DecorativeCircle : public DecorativeGeometry {
public:
    explicit DecorativeCircle(Real radius=0.5);

    void setRadius(Real);
    Real getRadius() const;

    SimTK_PIMPL_DOWNCAST(DecorativeCircle, DecorativeGeometry);
private:
    class DecorativeCircleRep& updRep();
    const DecorativeCircleRep& getRep() const;
};

class SimTK_SimTKCOMMON_EXPORT DecorativeSphere : public DecorativeGeometry {
public:
    explicit DecorativeSphere(Real radius=0.5);

    void setRadius(Real);
    Real getRadius() const;

    SimTK_PIMPL_DOWNCAST(DecorativeSphere, DecorativeGeometry);
private:
    class DecorativeSphereRep& updRep();
    const DecorativeSphereRep& getRep() const;
};

class SimTK_SimTKCOMMON_EXPORT DecorativeEllipsoid : public DecorativeGeometry {
public:
    explicit DecorativeEllipsoid(const Vec3& radii = Vec3(0.5,1/3.,0.25));

    void setRadii(const Vec3&);
    const Vec3& getRadii() const;

    SimTK_PIMPL_DOWNCAST(DecorativeEllipsoid, DecorativeGeometry);
private:
    class DecorativeEllipsoidRep& updRep();
    const DecorativeEllipsoidRep& getRep() const;
};

class SimTK_SimTKCOMMON_EXPORT DecorativeBrick : public DecorativeGeometry {
public:
    explicit DecorativeBrick(const Vec3& halfLengths = Vec3(0.5));

    void setHalfLengths(const Vec3&);
    const Vec3& getHalfLengths() const;

    SimTK_PIMPL_DOWNCAST(DecorativeBrick, DecorativeGeometry);
private:
    class DecorativeBrickRep& updRep();
    const DecorativeBrickRep& getRep() const;
};

class SimTK_SimTKCOMMON_EXPORT DecorativeCylinder : public DecorativeGeometry {
public:
    explicit DecorativeCylinder(Real radius=0.5, Real halfHeight=0.5);

    void setRadius(Real);
    void setHalfHeight(Real);
    Real getRadius() const;
    Real getHalfHeight() const;

    SimTK_PIMPL_DOWNCAST(DecorativeCylinder, DecorativeGeometry);
private:
    class DecorativeCylinderRep& updRep();
    const DecorativeCylinderRep& getRep() const;
};

class SimTK_SimTKCOMMON_EXPORT DecorativeFrame : public DecorativeGeometry {
public:
    explicit DecorativeFrame(Real axisLength=1);

    void setAxisLength(Real);
    Real getAxisLength() const;

    SimTK_PIMPL_DOWNCAST(DecorativeFrame, DecorativeGeometry);
private:
    class DecorativeFrameRep& updRep();
    const DecorativeFrameRep& getRep() const;
};

class SimTK_SimTKCOMMON_EXPORT DecorativeText : public DecorativeGeometry {
public:
    explicit DecorativeText(const std::string& label="");

    void setText(const std::string& label);
    const std::string& getText() const;

    SimTK_PIMPL_DOWNCAST(DecorativeText, DecorativeGeometry);
private:
    class DecorativeTextRep& updRep();
    const DecorativeTextRep& getRep() const;
};

class SimTK_SimTKCOMMON_EXPORT DecorativeMesh : public DecorativeGeometry {
public:
    explicit DecorativeMesh(const PolygonalMesh& mesh);
    const PolygonalMesh& getMesh() const;

    SimTK_PIMPL_DOWNCAST(DecorativeMesh, DecorativeGeometry);
private:
    class DecorativeMeshRep& updRep();
    const DecorativeMeshRep& getRep() const;
};

class SimTK_SimTKCOMMON_EXPORT DecorativeGeometryImplementation {
public:
    virtual ~DecorativeGeometryImplementation() { }
    virtual void implementLineGeometry(     const DecorativeLine&)     = 0;
    virtual void implementBrickGeometry(    const DecorativeBrick&)    = 0;
    virtual void implementCylinderGeometry( const DecorativeCylinder&) = 0;
    virtual void implementCircleGeometry(   const DecorativeCircle&)   = 0; 
    virtual void implementSphereGeometry(   const DecorativeSphere&)   = 0;
    virtual void implementEllipsoidGeometry(const DecorativeEllipsoid&)= 0;
    virtual void implementFrameGeometry(    const DecorativeFrame&)    = 0;
    virtual void implementTextGeometry(     const DecorativeText&)     = 0;
    virtual void implementMeshGeometry(     const DecorativeMesh&)     = 0;

    // TODO: wrappers for binary compatibility
};

} // namespace SimTK

#endif // SimTK_SimTKCOMMON_DECORATIVE_GEOMETRY_H_