CPolyhedron.h

Go to the documentation of this file.

/* +------------------------------------------------------------------------+
   |                     Mobile Robot Programming Toolkit (MRPT)            |
   |                          http://www.mrpt.org/                          |
   |                                                                        |
   | Copyright (c) 2005-2017, Individual contributors, see AUTHORS file     |
   | See: http://www.mrpt.org/Authors - All rights reserved.                |
   | Released under BSD License. See details in http://www.mrpt.org/License |
   +------------------------------------------------------------------------+ */
#ifndef opengl_CPolyhedron_H
#define opengl_CPolyhedron_H

#include <mrpt/opengl/CRenderizableDisplayList.h>
#include <mrpt/math/geometry.h>

namespace mrpt
{
namespace opengl
{
class CPolyhedron;

/**
  * This class represents arbitrary polyhedra. The class includes a set of
 * static methods to create common polyhedrons. The class includes many methods
 * to create standard polyhedra, not intended to be fast but to be simple. For
 * example, the dodecahedron is not created efficiently: first, an icosahedron
 * is created, and a duality operator is applied to it, which yields the
 * dodecahedron. This way, code is much smaller, although much slower. This is
 * not a big problem, since polyhedron creation does not usually take a
 * significant amount of time (they are created once and rendered many times).
  * Polyhedra information and models have been gotten from the Wikipedia,
 * http://wikipedia.org
  * \sa opengl::COpenGLScene
  *
  *  <div align="center">
  *  <table border="0" cellspan="4" cellspacing="4" style="border-width: 1px;
 * border-style: solid;">
  *   <tr> <td> mrpt::opengl::CPolyhedron </td> <td> \image html
 * preview_CPolyhedron.png </td> </tr>
  *  </table>
  *  </div>
  *
  * \ingroup mrpt_opengl_grp
  */
class CPolyhedron : public CRenderizableDisplayList
{
        DEFINE_SERIALIZABLE(CPolyhedron)
   public:
        /**
          * Struct used to store a polyhedron edge. The struct consists only of two
         * vertex indices, used to access the polyhedron vertex list.
          */
        struct TPolyhedronEdge
        {
                /**
                  * First vertex.
                  */
                uint32_t v1;
                /**
                  * Second vertex.
                  */
                uint32_t v2;
                /**
                  * Default constructor. Initializes to garbage.
                  */
                TPolyhedronEdge() : v1(), v2() {}
                /**
                  * Comparison agains another edge. Simmetry is taken into account.
                  */
                bool operator==(const TPolyhedronEdge& e) const
                {
                        if (e.v1 == v1 && e.v2 == v2)
                                return true;
                        else
                                return e.v1 == v2 && e.v2 == v1;
                }
                /**
                  * Given a set of vertices, computes the length of the vertex.
                  */
                double length(const std::vector<mrpt::math::TPoint3D>& vs) const;
                /**
                  * Destructor.
                  */
                ~TPolyhedronEdge() {}
        };
        /**
          * Struct used to store a polyhedron face. Consists on a set of vertex
         * indices and a normal vector.
          */
        struct TPolyhedronFace
        {
                /** Vector of indices to the vertex list. */
                std::vector<uint32_t> vertices;
                /** Normal vector. */
                double normal[3];
                /** Fast default constructor. Initializes to garbage. */
                TPolyhedronFace() : vertices() {}
                /** Destructor.  */
                ~TPolyhedronFace() {}
                /** Given a set of vertices, computes the area of this face. */
                double area(const std::vector<mrpt::math::TPoint3D>& vertices) const;
                /** Given a set of vertices, get this face's center. */
                void getCenter(
                        const std::vector<mrpt::math::TPoint3D>& vertices,
                        mrpt::math::TPoint3D& p) const;
        };

   protected:
        /**
          * List of vertices presents in the polyhedron.
          */
        std::vector<mrpt::math::TPoint3D> mVertices;
        /**
          * List of polyhedron's edges.
          */
        std::vector<TPolyhedronEdge> mEdges;
        /**
          * List of polyhedron's faces.
          */
        std::vector<TPolyhedronFace> mFaces;
        /**
          * This flag determines whether the polyhedron will be displayed as a solid
         * object or as a set of edges.
          */
        bool mWireframe;
        /**
          * When displaying as wireframe object, this variable stores the width of
         * the edges.
          */
        double mLineWidth;
        /**
          * Mutable list of actual polygons, maintained for speed.
          */
        mutable std::vector<mrpt::math::TPolygonWithPlane> tempPolygons;
        /**
          * Whether the set of actual polygons is up to date or not.
          */
        mutable bool polygonsUpToDate;

   public:
        /** Evaluates the bounding box of this object (including possible children)
         * in the coordinate frame of the object parent. */
        void getBoundingBox(
                mrpt::math::TPoint3D& bb_min,
                mrpt::math::TPoint3D& bb_max) const override;

        // Static methods to create frequent polyhedra. More bizarre polyhedra are
        // intended to be added in a near future.

        /** @name Platonic solids.
                @{
         */
        /**
          * Creates a regular tetrahedron (see
          http://en.wikipedia.org/wiki/Tetrahedron). The tetrahedron is created as a
          triangular pyramid whose edges and vertices are transitive.
          * The tetrahedron is the dual to itself.
          <p align="center"><img src="Tetrahedron.gif"></p>
          * \sa
          CreatePyramid,CreateJohnsonSolidWithConstantBase,CreateTruncatedTetrahedron
          */
        static CPolyhedron::Ptr CreateTetrahedron(double radius);
        /**
          * Creates a regular cube, also called hexahedron (see
          http://en.wikipedia.org/wiki/Hexahedron). The hexahedron is created as a
          cubic prism which transitive edges. Another ways to create it include:
          <ul><li>Dual to an octahedron.</li><li>Parallelepiped with three
          orthogonal, equally-lengthed vectors.</li><li>Triangular trapezohedron
          with proper height.</li></ul>
          <p align="center"><img src="Hexahedron.gif"></p>
          * \sa
          CreateOctahedron,getDual,CreateParallelepiped,CreateTrapezohedron,CreateTruncatedHexahedron,CreateTruncatedOctahedron,CreateCuboctahedron,CreateRhombicuboctahedron
          */
        static CPolyhedron::Ptr CreateHexahedron(double radius);
        /**
          * Creates a regular octahedron (see
          http://en.wikipedia.org/wiki/Octahedron). The octahedron is created as a
          square bipyramid whit transitive edges and vertices. Another ways to
          create an octahedron are:
          <ul><li>Dual to an hexahedron</li><li>Triangular antiprism with transitive
          vertices.</li><li>Conveniently truncated tetrahedron.</li></ul>
          <p align="center"><img src="Octahedron.gif"></p>
          * \sa
          CreateHexahedron,getDual,CreateArchimedeanAntiprism,CreateTetrahedron,truncate,CreateTruncatedOctahedron,CreateTruncatedHexahedron,CreateCuboctahedron,CreateRhombicuboctahedron
          */
        static CPolyhedron::Ptr CreateOctahedron(double radius);
        /**
          * Creates a regular dodecahedron (see
          http://en.wikipedia.org/wiki/Dodecahedron). The dodecahedron is created as
          the dual to an icosahedron.
          <p align="center"><img src="Dodecahedron.gif"></p>
          * \sa
          CreateIcosahedron,getDual,CreateTruncatedDodecahedron,CreateTruncatedIcosahedron,CreateIcosidodecahedron,CreateRhombicosidodecahedron
          */
        static CPolyhedron::Ptr CreateDodecahedron(double radius);
        /**
          * Creates a regular icosahedron (see
          http://en.wikipedia.org/wiki/Icosahedron). The icosahedron is created as a
          gyroelongated pentagonal bipyramid with transitive edges, and it's the
          dual to a dodecahedron.
          <p align="center"><img src="Icosahedron.gif"></p>
          * \sa
          CreateJohnsonSolidWithConstantBase,CreateDodecahedron,getDual,CreateTruncatedIcosahedron,CreateTruncatedDodecahedron,CreateIcosidodecahedron,CreateRhombicosidodecahedron
          */
        static CPolyhedron::Ptr CreateIcosahedron(double radius);
        /** @}
          */

        /** @name Archimedean solids.
                @{
         */
        /**
          * Creates a truncated tetrahedron, consisting of four triangular faces and
          for hexagonal ones (see
          http://en.wikipedia.org/wiki/Truncated_tetrahedron). Its dual is the
          triakis tetrahedron.
          <p align="center"><img src="Truncatedtetrahedron.gif"></p>
          * \sa CreateTetrahedron,CreateTriakisTetrahedron
          */
        static CPolyhedron::Ptr CreateTruncatedTetrahedron(double radius);
        /**
          * Creates a cuboctahedron, consisting of six square faces and eight
          triangular ones (see http://en.wikipedia.org/wiki/Cuboctahedron). There
          are several ways to create a cuboctahedron:
          <ul><li>Hexahedron truncated to a certain extent.</li><li>Octahedron
          truncated to a certain extent.</li><li>Cantellated
          tetrahedron</li><li>Dual to a rhombic dodecahedron.</li></ul>
          <p align="center"><img src="Cuboctahedron.gif"></p>
          * \sa
          CreateHexahedron,CreateOctahedron,truncate,CreateTetrahedron,cantellate,CreateRhombicuboctahedron,CreateRhombicDodecahedron,
          */
        static CPolyhedron::Ptr CreateCuboctahedron(double radius);
        /**
          * Creates a truncated hexahedron, with six octogonal faces and eight
          triangular ones (see http://en.wikipedia.org/wiki/Truncated_hexahedron).
          The truncated octahedron is dual to the triakis octahedron.
          <p align="center"><img src="Truncatedhexahedron.gif"></p>
          * \sa CreateHexahedron,CreateTriakisOctahedron
          */
        static CPolyhedron::Ptr CreateTruncatedHexahedron(double radius);
        /**
          * Creates a truncated octahedron, with eight hexagons and eight squares
          (see http://en.wikipedia.org/wiki/Truncated_octahedron). It's the dual to
          the tetrakis hexahedron.
          <p align="center"><img src="Truncatedoctahedron.gif"></p>
          * \sa CreateOctahedron,CreateTetrakisHexahedron
          */
        static CPolyhedron::Ptr CreateTruncatedOctahedron(double radius);
        /**
          * Creates a rhombicuboctahedron, with 18 squares and 8 triangles (see
          http://en.wikipedia.org/wiki/Rhombicuboctahedron), calculated as an
          elongated square bicupola. It can also be calculated as a cantellated
          hexahedron or octahedron, and its dual is the deltoidal icositetrahedron.
          * If the second argument is set to false, the lower cupola is rotated, so
          that the objet created is an elongated square gyrobicupola (see
          http://en.wikipedia.org/wiki/Elongated_square_gyrobicupola). This is not
          an archimedean solid, but a Johnson one, since it hasn't got vertex
          transitivity.
          <p align="center"><img src="Rhombicuboctahedron.gif"></p>
          * \sa
          CreateJohnsonSolidWithConstantBase,CreateHexahedron,CreateOctahedron,cantellate,CreateCuboctahedron,CreateDeltoidalIcositetrahedron
          */
        static CPolyhedron::Ptr CreateRhombicuboctahedron(
                double radius, bool type = true);
        /**
          * Creates an icosidodecahedron, with 12 pentagons and 20 triangles (see
          http://en.wikipedia.org/wiki/Icosidodecahedron). Certain truncations of
          either a dodecahedron or an icosahedron yield an icosidodecahedron.
          * The dual of the icosidodecahedron is the rhombic triacontahedron.
          * If the second argument is set to false, the lower rotunda is rotated. In
          this case, the object created is a pentagonal orthobirotunda (see
          http://en.wikipedia.org/wiki/Pentagonal_orthobirotunda). This object
          presents symmetry against the XY plane and is not vertex transitive, so
          it's a Johnson's solid.
          <p align="center"><img src="Icosidodecahedron.gif"></p>
          * \sa
          CreateDodecahedron,CreateIcosahedron,truncate,CreateRhombicosidodecahedron,CreateRhombicTriacontahedron
          */
        static CPolyhedron::Ptr CreateIcosidodecahedron(
                double radius, bool type = true);
        /**
          * Creates a truncated dodecahedron, consisting of 12 dodecagons and 20
          triangles (see http://en.wikipedia.org/wiki/Truncated_dodecahedron). The
          truncated dodecahedron is the dual to the triakis icosahedron.
          <p align="center"><img src="Truncateddodecahedron.gif"></p>
          * \sa CreateDodecahedron,CreateTriakisIcosahedron
          */
        static CPolyhedron::Ptr CreateTruncatedDodecahedron(double radius);
        /**
          * Creates a truncated icosahedron, consisting of 20 hexagons and 12
          pentagons. This object resembles a typical soccer ball (see
          http://en.wikipedia.org/wiki/Truncated_icosahedron). The pentakis
          dodecahedron is the dual to the truncated icosahedron.
          <p align="center"><img src="Truncatedicosahedron.gif"></p>
          * \sa CreateIcosahedron,CreatePentakisDodecahedron
          */
        static CPolyhedron::Ptr CreateTruncatedIcosahedron(double radius);
        /**
          * Creates a rhombicosidodecahedron, consisting of 30 squares, 12 pentagons
          and 20 triangles (see
          http://en.wikipedia.org/wiki/Rhombicosidodecahedron). This object can be
          obtained as the cantellation of either a dodecahedron or an icosahedron.
          The dual of the rhombicosidodecahedron is the deltoidal hexecontahedron.
          <p align="center"><img src="Rhombicosidodecahedron.gif"></p>
          * \sa
          CreateDodecahedron,CreateIcosahedron,CreateIcosidodecahedron,CreateDeltoidalHexecontahedron
          */
        static CPolyhedron::Ptr CreateRhombicosidodecahedron(double radius);
        /** @}
         */

        /** @name Other Johnson solids.
                @{
         */
        /**
          * Creates a pentagonal rotunda (half an icosidodecahedron), consisting of
         * six pentagons, ten triangles and a decagon (see
         * http://en.wikipedia.org/wiki/Pentagonal_rotunda).
          * \sa CreateIcosidodecahedron,CreateJohnsonSolidWithConstantBase
          */
        static CPolyhedron::Ptr CreatePentagonalRotunda(double radius);
        /** @}
         */

        /** @name Catalan solids.
                @{
        */
        /**
          * Creates a triakis tetrahedron, dual to the truncated tetrahedron. This
          body consists of 12 isosceles triangles (see
          http://en.wikipedia.org/wiki/Triakis_tetrahedron).
          <p align="center"><img src="Triakistetrahedron.gif"></p>
          * \sa CreateTruncatedTetrahedron
          */
        static CPolyhedron::Ptr CreateTriakisTetrahedron(double radius);

        /**
          * Creates a rhombic dodecahedron, dual to the cuboctahedron. This body
          consists of 12 rhombi (see
          http://en.wikipedia.org/wiki/Rhombic_dodecahedron).
          <p align="center"><img src="Rhombicdodecahedron.gif"></p>
          * \sa CreateCuboctahedron
          */
        static CPolyhedron::Ptr CreateRhombicDodecahedron(double radius);

        /**
          * Creates a triakis octahedron, dual to the truncated hexahedron. This
          body consists of 24 isosceles triangles (see
          http://en.wikipedia.org/wiki/Triakis_octahedron).
          <p align="center"><img src="Triakisoctahedron.gif"></p>
          * \sa CreateTruncatedHexahedron
          */
        static CPolyhedron::Ptr CreateTriakisOctahedron(double radius);

        /**
          * Creates a tetrakis hexahedron, dual to the truncated octahedron. This
          body consists of 24 isosceles triangles (see
          http://en.wikipedia.org/wiki/Tetrakis_hexahedron).
          <p align="center"><img src="Tetrakishexahedron.gif"></p>
          * \sa CreateTruncatedOctahedron
          */
        static CPolyhedron::Ptr CreateTetrakisHexahedron(double radius);

        /**
          * Creates a deltoidal icositetrahedron, dual to the rhombicuboctahedron.
          This body consists of 24 kites (see
          http://en.wikipedia.org/wiki/Deltoidal_icositetrahedron).
          <p align="center"><img src="Deltoidalicositetrahedron.gif"></p>
          * \sa CreateRhombicuboctahedron
          */
        static CPolyhedron::Ptr CreateDeltoidalIcositetrahedron(double radius);

        /**
          * Creates a rhombic triacontahedron, dual to the icosidodecahedron. This
          body consists of 30 rhombi (see
          http://en.wikipedia.org/wiki/Rhombic_triacontahedron).
          <p align="center"><img src="Rhombictriacontahedron.gif"></p>
          * \sa CreateIcosidodecahedron
          */
        static CPolyhedron::Ptr CreateRhombicTriacontahedron(double radius);

        /**
          * Creates a triakis icosahedron, dual to the truncated dodecahedron. This
          body consists of 60 isosceles triangles
          http://en.wikipedia.org/wiki/Triakis_icosahedron).
          <p align="center"><img src="Triakisicosahedron.gif"></p>
          * \sa CreateTruncatedDodecahedron
          */
        static CPolyhedron::Ptr CreateTriakisIcosahedron(double radius);

        /**
          * Creates a pentakis dodecahedron, dual to the truncated icosahedron. This
          body consists of 60 isosceles triangles (see
          http://en.wikipedia.org/wiki/Pentakis_dodecahedron).
          <p align="center"><img src="Pentakisdodecahedron.gif"></p>
          * \sa CreateTruncatedIcosahedron
          */
        static CPolyhedron::Ptr CreatePentakisDodecahedron(double radius);

        /**
          * Creates a deltoidal hexecontahedron, dual to the rhombicosidodecahedron.
          This body consists of 60 kites (see
          http://en.wikipedia.org/wiki/Deltoidal_hexecontahedron).
          <p align="center"><img src="Deltoidalhexecontahedron.gif"></p>
          * \sa CreateRhombicosidodecahedron
          */
        static CPolyhedron::Ptr CreateDeltoidalHexecontahedron(double radius);
        /** @}
         */

        /** @name Customizable polyhedra
                @{
         */
        /**
          * Creates a cubic prism, given the coordinates of two opposite vertices.
         * Each edge will be parallel to one of the coordinate axes, although the
         * orientation may change by assigning a pose to the object.
          * \sa CreateCubicPrism(const mrpt::math::TPoint3D &,const
         * mrpt::math::TPoint3D
         * &),CreateParallelepiped,CreateCustomPrism,CreateRegularPrism,CreateArchimedeanRegularPrism
          */
        static CPolyhedron::Ptr CreateCubicPrism(
                double x1, double x2, double y1, double y2, double z1, double z2);
        /**
          * Creates a cubic prism, given two opposite vertices.
          * \sa
         * CreateCubicPrism(double,double,double,double,double,double),CreateParallelepiped,CreateCustomPrism,CreateRegularPrism,CreateArchimedeanRegularPrism
          */
        static CPolyhedron::Ptr CreateCubicPrism(
                const mrpt::math::TPoint3D& p1, const mrpt::math::TPoint3D& p2);
        /**
          * Creates a custom pyramid, using a set of 2D vertices which will lie on
         * the XY plane.
          * \sa
         * CreateDoublePyramid,CreateFrustum,CreateBifrustum,CreateRegularPyramid
          */
        static CPolyhedron::Ptr CreatePyramid(
                const std::vector<mrpt::math::TPoint2D>& baseVertices, double height);
        /**
          * Creates a double pyramid, using a set of 2D vertices which will lie on
         * the XY plane. The second height is used with the downwards pointing
         * pyramid, so that it will effectively point downwards if it's positive.
          * \sa CreatePyramid,CreateBifrustum,CreateRegularDoublePyramid
          */
        static CPolyhedron::Ptr CreateDoublePyramid(
                const std::vector<mrpt::math::TPoint2D>& baseVertices, double height1,
                double height2);
        /**
          * Creates a truncated pyramid, using a set of vertices which will lie on
         * the XY plane.
          * Do not try to use with a ratio equal to zero; use CreatePyramid instead.
         * When using a ratio of 1, it will create a Prism.
          * \sa CreatePyramid,CreateBifrustum
          */
        static CPolyhedron::Ptr CreateTruncatedPyramid(
                const std::vector<mrpt::math::TPoint2D>& baseVertices, double height,
                double ratio);
        /**
          * This is a synonym for CreateTruncatedPyramid.
          * \sa CreateTruncatedPyramid
          */
        static CPolyhedron::Ptr CreateFrustum(
                const std::vector<mrpt::math::TPoint2D>& baseVertices, double height,
                double ratio);
        /**
          * Creates a custom prism with vertical edges, given any base which will
         * lie on the XY plane.
          * \sa
         * CreateCubicPrism,CreateCustomAntiprism,CreateRegularPrism,CreateArchimedeanRegularPrism
          */
        static CPolyhedron::Ptr CreateCustomPrism(
                const std::vector<mrpt::math::TPoint2D>& baseVertices, double height);
        /**
          * Creates a custom antiprism, using two custom bases. For better results,
         * the top base should be slightly rotated with respect to the bottom one.
          * \sa
         * CreateCustomPrism,CreateRegularAntiprism,CreateArchimedeanRegularAntiprism
          */
        static CPolyhedron::Ptr CreateCustomAntiprism(
                const std::vector<mrpt::math::TPoint2D>& bottomBase,
                const std::vector<mrpt::math::TPoint2D>& topBase, double height);
        /**
          * Creates a parallelepiped, given a base point and three vectors
         * represented as points.
          * \sa CreateCubicPrism
          */
        static CPolyhedron::Ptr CreateParallelepiped(
                const mrpt::math::TPoint3D& base, const mrpt::math::TPoint3D& v1,
                const mrpt::math::TPoint3D& v2, const mrpt::math::TPoint3D& v3);
        /**
          * Creates a bifrustum, or double truncated pyramid, given a base which
         * will lie on the XY plane.
          * \sa CreateFrustum,CreateDoublePyramid
          */
        static CPolyhedron::Ptr CreateBifrustum(
                const std::vector<mrpt::math::TPoint2D>& baseVertices, double height1,
                double ratio1, double height2, double ratio2);
        /**
          * Creates a trapezohedron, consisting of 2*N kites, where N is the number
         * of edges in the base. The base radius controls the polyhedron height,
         * whilst the distance between bases affects the height.
          * When the number of edges equals 3, the polyhedron is actually a
         * parallelepiped, and it can even be a cube.
          */
        static CPolyhedron::Ptr CreateTrapezohedron(
                uint32_t numBaseEdges, double baseRadius, double basesDistance);
        /**
          * Creates an antiprism whose base is a regular polygon. The upper base is
         * rotated \f$\frac\pi N\f$ with respect to the lower one, where N is the
         * number of vertices in the base, and thus the lateral triangles are
         * isosceles.
          * \sa CreateCustomAntiprism,CreateArchimedeanRegularAntiprism
          */
        static CPolyhedron::Ptr CreateRegularAntiprism(
                uint32_t numBaseEdges, double baseRadius, double height);
        /**
          * Creates a regular prism whose base is a regular polygon and whose edges
         * are either parallel or perpendicular to the XY plane.
          * \sa CreateCubicPrism,CreateCustomPrism,CreateArchimedeanRegularAntiprism
          */
        static CPolyhedron::Ptr CreateRegularPrism(
                uint32_t numBaseEdges, double baseRadius, double height);
        /**
          * Creates a regular pyramid whose base is a regular polygon.
          * \sa CreatePyramid
          */
        static CPolyhedron::Ptr CreateRegularPyramid(
                uint32_t numBaseEdges, double baseRadius, double height);
        /**
          * Creates a regular double pyramid whose base is a regular polygon.
          * \sa CreateDoublePyramid
          */
        static CPolyhedron::Ptr CreateRegularDoublePyramid(
                uint32_t numBaseEdges, double baseRadius, double height1,
                double height2);
        /**
          * Creates a regular prism whose lateral area is comprised of squares, and
         * so each face of its is a regular polygon. Due to vertex transitivity, the
         * resulting object is always archimedean.
          * \sa CreateRegularPrism,CreateCustomPrism
          */
        static CPolyhedron::Ptr CreateArchimedeanRegularPrism(
                uint32_t numBaseEdges, double baseRadius);
        /**
          * Creates a regular antiprism whose lateral polygons are equilateral
         * triangles, and so each face of its is a regular polygon. Due to vertex
         * transitivity, the resulting object is always archimedean.
          * \sa CreateRegularAntiprism,CreateCustomAntiprism
          */
        static CPolyhedron::Ptr CreateArchimedeanRegularAntiprism(
                uint32_t numBaseEdges, double baseRadius);
        /**
          * Creates a regular truncated pyramid whose base is a regular polygon.
          * \sa CreateTruncatedPyramid
          */
        static CPolyhedron::Ptr CreateRegularTruncatedPyramid(
                uint32_t numBaseEdges, double baseRadius, double height, double ratio);
        /**
          * This is a synonym for CreateRegularTruncatedPyramid.
          * \sa CreateRegularTruncatedPyramid
          */
        static CPolyhedron::Ptr CreateRegularFrustum(
                uint32_t numBaseEdges, double baseRadius, double height, double ratio);
        /**
          * Creates a bifrustum (double truncated pyramid) whose base is a regular
         * polygon lying in the XY plane.
          * \sa CreateBifrustum
          */
        static CPolyhedron::Ptr CreateRegularBifrustum(
                uint32_t numBaseEdges, double baseRadius, double height1, double ratio1,
                double height2, double ratio2);
        /**
          * Creates a cupola.
          * \throw std::logic_error if the number of edges is odd or less than four.
          */
        static CPolyhedron::Ptr CreateCupola(
                uint32_t numBaseEdges, double edgeLength);
        /**
          * Creates a trapezohedron whose dual is exactly an archimedean antiprism.
         * Creates a cube if numBaseEdges is equal to 3.
          * \todo Actually resulting height is significantly higher than that passed
         * to the algorithm.
          * \sa CreateTrapezohedron,CreateArchimedeanRegularAntiprism,getDual
          */
        static CPolyhedron::Ptr CreateCatalanTrapezohedron(
                uint32_t numBaseEdges, double height);
        /**
          * Creates a double pyramid whose dual is exactly an archimedean prism.
         * Creates an octahedron if numBaseEdges is equal to 4.
          * \todo Actually resulting height is significantly higher than that passed
         * to the algorithm.
          * \sa CreateDoublePyramid,CreateArchimedeanRegularPrism,getDual
          */
        static CPolyhedron::Ptr CreateCatalanDoublePyramid(
                uint32_t numBaseEdges, double height);
        /**
          * Creates a series of concatenated solids (most of which are prismatoids)
          whose base is a regular polygon with a given number of edges. Every face
          of the resulting body will be a regular polygon, so it is a Johnson solid;
          in special cases, it may be archimedean or even platonic.
          * The shape of the body is defined by the string argument, which can
          include one or more of the following:
          <center><table>
          <tr><td><b>String</b></td><td><b>Body</b></td><td><b>Restrictions</b></td></tr>
          <tr><td>P+</td><td>Upward pointing pyramid</td><td>Must be the last
          object, vertex number cannot surpass 5</td></tr>
          <tr><td>P-</td><td>Downward pointing pyramid</td><td>Must be the first
          object, vertex number cannot surpass 5</td></tr>
          <tr><td>C+</td><td>Upward pointing cupola</td><td>Must be the last object,
          vertex number must be an even number in the range 4-10.</td></tr>
          <tr><td>C-</td><td>Downward pointing cupola</td><td>Must be the first
          object, vertex number must be an even number in the range 4-10.</td></tr>
          <tr><td>GC+</td><td>Upward pointing cupola, rotated</td><td>Must be the
          last object, vertex number must be an even number in the range
          4-10.</td></tr>
          <tr><td>GC-</td><td>Downward pointing cupola, rotated</td><td>Must be the
          first object, vertex number must be an even number in the range
          4-10.</td></tr>
          <tr><td>PR</td><td>Archimedean prism</td><td>Cannot abut other
          prism</td></tr>
          <tr><td>A</td><td>Archimedean antiprism</td><td>None</td></tr>
          <tr><td>R+</td><td>Upward pointing rotunda</td><td>Must be the last
          object, vertex number must be exactly 10</td></tr>
          <tr><td>R-</td><td>Downward pointing rotunda</td><td>Must be the first
          object, vertex number must be exactly 10</td></tr>
          <tr><td>GR+</td><td>Upward pointing rotunda, rotated</td><td>Must be the
          last object, vertex number must be exactly 10</td></tr>
          <tr><td>GR-</td><td>Downward pointing rotunda</td><td>Must be the first
          object, vertex number must be exactly 10</td></tr>
          </table></center>
          * Some examples of bodies are:
          <center><table>
          <tr><td><b>String</b></td><td><b>Vertices</b></td><td><b>Resulting
          body</b></td></tr>
          <tr><td>P+</td><td align="center">3</td><td>Tetrahedron</td></tr>
          <tr><td>PR</td><td align="center">4</td><td>Hexahedron</td></tr>
          <tr><td>P-P+</td><td align="center">4</td><td>Octahedron</td></tr>
          <tr><td>A</td><td align="center">3</td><td>Octahedron</td></tr>
          <tr><td>C+PRC-</td><td
          align="center">8</td><td>Rhombicuboctahedron</td></tr>
          <tr><td>P-AP+</td><td align="center">5</td><td>Icosahedron</td></tr>
          <tr><td>R-R+</td><td align="center">10</td><td>Icosidodecahedron</td></tr>
          </table></center>
          */
        static CPolyhedron::Ptr CreateJohnsonSolidWithConstantBase(
                uint32_t numBaseEdges, double baseRadius, const std::string& components,
                size_t shifts = 0);
        /** @}
         */

        /**
          * Render
          * \sa CRenderizable
          */
        void render_dl() const override;
        /**
          * Ray trace
          * \sa CRenderizable
          */
        bool traceRay(const mrpt::poses::CPose3D& o, double& dist) const override;
        /**
          * Gets a list with the polyhedron's vertices.
          */
        inline void getVertices(std::vector<mrpt::math::TPoint3D>& vertices) const
        {
                vertices = mVertices;
        }
        /**
          * Gets a list with the polyhedron's edges.
          */
        inline void getEdges(std::vector<TPolyhedronEdge>& edges) const
        {
                edges = mEdges;
        }
        /**
          * Gets a list with the polyhedron's faces.
          */
        inline void getFaces(std::vector<TPolyhedronFace>& faces) const
        {
                faces = mFaces;
        }
        /**
          * Gets the amount of vertices.
          */
        inline uint32_t getNumberOfVertices() const { return mVertices.size(); }
        /**
          * Gets the amount of edges.
          */
        inline uint32_t getNumberOfEdges() const { return mEdges.size(); }
        /**
          * Gets the amount of faces.
          */
        inline uint32_t getNumberOfFaces() const { return mFaces.size(); }
        /**
          * Gets a vector with each edge's length.
          */
        void getEdgesLength(std::vector<double>& lengths) const;
        /**
          * Gets a vector with each face's area. Won't work properly if the polygons
         * are not convex.
          */
        void getFacesArea(std::vector<double>& areas) const;
        /**
          * Gets the polyhedron volume. Won't work properly if the polyhedron is not
         * convex.
          */
        double getVolume() const;
        /**
          * Returns whether the polyhedron will be rendered as a wireframe object.
          */
        inline bool isWireframe() const { return mWireframe; }
        /**
          * Sets whether the polyhedron will be rendered as a wireframe object.
          */
        inline void setWireframe(bool enabled = true)
        {
                mWireframe = enabled;
                CRenderizableDisplayList::notifyChange();
        }
        /**
          * Gets the wireframe lines width.
          */
        inline double getLineWidth() const { return mLineWidth; }
        /**
          * Sets the width used to render lines, when wireframe rendering is
         * activated.
          */
        inline void setLineWidth(double lineWidth)
        {
                mLineWidth = lineWidth;
                CRenderizableDisplayList::notifyChange();
        }
        /**
          * Gets the polyhedron as a set of polygons.
          * \sa mrpt::math::TPolygon3D
          */
        void getSetOfPolygons(std::vector<math::TPolygon3D>& vec) const;
        /**
          * Gets the polyhedron as a set of polygons, with the pose transformation
         * already applied.
          * \sa mrpt::math::TPolygon3D,mrpt::poses::CPose3D
          */
        void getSetOfPolygonsAbsolute(std::vector<math::TPolygon3D>& vec) const;
        /** Gets the intersection of two polyhedra, either as a set or as a matrix
         * of intersections. Each intersection is represented by a TObject3D.
          * \sa mrpt::math::TObject3D
          */
        template <class T>
        inline static size_t getIntersection(
                const CPolyhedron::Ptr& p1, const CPolyhedron::Ptr& p2, T& container);
        /**
          * Returns true if the polygon is a completely closed object.
          */
        inline bool isClosed() const
        {
                for (size_t i = 0; i < mVertices.size(); i++)
                        if (edgesInVertex(i) != facesInVertex(i)) return false;
                return true;
        }
        /**
          * Recomputes polygons, if necessary, so that each one is convex.
          */
        void makeConvexPolygons();
        /**
          * Gets the center of the polyhedron.
          */
        void getCenter(mrpt::math::TPoint3D& center) const;
        /**
          * Creates a random polyhedron from the static methods.
          */
        static CPolyhedron::Ptr CreateRandomPolyhedron(double radius);

        /** @name Polyhedron special operations.
                @{
         */
        /**
          * Given a polyhedron, creates its dual.
          * \sa truncate,cantellate,augment
          * \throw std::logic_error Can't get the dual to this polyhedron.
          */
        CPolyhedron::Ptr getDual() const;
        /**
          * Truncates a polyhedron to a given factor.
          * \sa getDual,cantellate,augment
          * \throw std::logic_error Polyhedron truncation results in skew polygons
         * and thus it's impossible to perform.
          */
        CPolyhedron::Ptr truncate(double factor) const;
        /**
          * Cantellates a polyhedron to a given factor.
          * \sa getDual,truncate,augment
          */
        CPolyhedron::Ptr cantellate(double factor) const;
        /**
          * Augments a polyhedron to a given height. This operation is roughly dual
         * to the truncation: given a body P, the operation dtdP and aP yield
         * resembling results.
          * \sa getDual,truncate,cantellate
          */
        CPolyhedron::Ptr augment(double height) const;
        /**
          * Augments a polyhedron to a given height. This method only affects to
         * faces with certain number of vertices.
          * \sa augment(double) const
          */
        CPolyhedron::Ptr augment(double height, size_t numVertices) const;
        /**
          * Augments a polyhedron, so that the resulting triangles are equilateral.
         * If the argument is true, triangles are "cut" from the polyhedron, instead
         * of being added.
          * \throw std::logic_error a non-regular face has been found.
          * \sa augment(double) const
          */
        CPolyhedron::Ptr augment(bool direction = false) const;
        /**
          * Augments a polyhedron, so that the resulting triangles are equilateral;
         * affects only faces with certain number of faces. If the second argument
         * is true, triangles are "cut" from the polyhedron.
          * \throw std::logic_error a non-regular face has been found.
          * \sa augment(double) const
          */
        CPolyhedron::Ptr augment(size_t numVertices, bool direction = false) const;
        /**
          * Rotates a polyhedron around the Z axis a given amount of radians. In
          *some cases, this operation may be necessary to view the symmetry between
          *related objects.
          *     \sa scale
          */
        CPolyhedron::Ptr rotate(double angle) const;
        /**
          * Scales a polyhedron to a given factor.
          * \throw std::logic_error factor is not a strictly positive number.
          * \sa rotate
          */
        CPolyhedron::Ptr scale(double factor) const;
        /** @}
         */
        /**
          * Updates the mutable list of polygons used in rendering and ray tracing.
          */
        void updatePolygons() const;

   private:
        /**
          * Generates a list of 2D vertices constituting a regular polygon.
          */
        static std::vector<mrpt::math::TPoint2D> generateBase(
                uint32_t numBaseEdges, double baseRadius);
        /**
          * Generates a list of 2D vertices constituting a regular polygon, with an
         * angle shift which makes it suitable for antiprisms.
          */
        static std::vector<mrpt::math::TPoint2D> generateShiftedBase(
                uint32_t numBaseEdges, double baseRadius);
        /**
          * Generates a list of 3D vertices constituting a regular polygon,
         * appending it to an existing vector.
          */
        static void generateBase(
                uint32_t numBaseEdges, double baseRadius, double height,
                std::vector<mrpt::math::TPoint3D>& vec);
        /**
          * Generates a list of 3D vertices constituting a regular polygon
         * conveniently shifted, appending it to an existing vector.
          */
        static void generateShiftedBase(
                uint32_t numBaseEdges, double baseRadius, double height, double shift,
                std::vector<mrpt::math::TPoint3D>& vec);
        /**
          * Calculates the normal vector to a face.
          */
        bool setNormal(TPolyhedronFace& f, bool doCheck = true);
        /**
          * Adds, to the existing list of edges, each edge in a given face.
          */
        void addEdges(const TPolyhedronFace& e);
        /**
          * Checks whether a set of faces is suitable for a set of vertices.
          */
        static bool checkConsistence(
                const std::vector<mrpt::math::TPoint3D>& vertices,
                const std::vector<TPolyhedronFace>& faces);
        /**
          * Returns how many edges converge in a given vertex.
          */
        size_t edgesInVertex(size_t vertex) const;
        /**
          * Returns how many faces converge in a given vertex.
          */
        size_t facesInVertex(size_t vertex) const;

   public:
        /**
          * Basic empty constructor.
          */
        inline CPolyhedron()
                : mVertices(),
                  mEdges(),
                  mFaces(),
                  mWireframe(false),
                  mLineWidth(1),
                  polygonsUpToDate(false)
        {
        }
        /**
          * Basic constructor with a list of vertices and another of faces, checking
         * for correctness.
          */
        inline CPolyhedron(
                const std::vector<mrpt::math::TPoint3D>& vertices,
                const std::vector<TPolyhedronFace>& faces, bool doCheck = true)
                : mVertices(vertices),
                  mEdges(),
                  mFaces(faces),
                  mWireframe(false),
                  mLineWidth(1),
                  polygonsUpToDate(false)
        {
                InitFromVertAndFaces(vertices, faces, doCheck);
        }
        inline void InitFromVertAndFaces(
                const std::vector<mrpt::math::TPoint3D>& vertices,
                const std::vector<TPolyhedronFace>& faces, bool doCheck = true)
        {
                if (doCheck && !checkConsistence(vertices, faces))
                        throw std::logic_error("Face list accesses a vertex out of range");
                for (std::vector<TPolyhedronFace>::iterator it = mFaces.begin();
                         it != mFaces.end(); ++it)
                {
                        if (!setNormal(*it, doCheck))
                                throw std::logic_error("Bad face specification");
                        addEdges(*it);
                }
        }

        CPolyhedron(const std::vector<math::TPolygon3D>& polys);

        CPolyhedron(
                const std::vector<mrpt::math::TPoint3D>& vertices,
                const std::vector<std::vector<uint32_t>>& faces);

        /** Creates a polyhedron without checking its correctness. */
        static CPolyhedron::Ptr CreateNoCheck(
                const std::vector<mrpt::math::TPoint3D>& vertices,
                const std::vector<TPolyhedronFace>& faces);
        /** Creates an empty Polyhedron. */
        static CPolyhedron::Ptr CreateEmpty();
        /** Destructor. */
        virtual ~CPolyhedron() {}
};

// Implemented after the definition of Smart::Ptrs in the _POST() macro above.
template <class T>
size_t CPolyhedron::getIntersection(
        const CPolyhedron::Ptr& p1, const CPolyhedron::Ptr& p2, T& container)
{
        std::vector<mrpt::math::TPolygon3D> polys1, polys2;
        p1->getSetOfPolygonsAbsolute(polys1);
        p2->getSetOfPolygonsAbsolute(polys2);
        return mrpt::math::intersect(polys1, polys2, container);
}

/**
  * Reads a polyhedron edge from a binary stream.
  */
mrpt::utils::CStream& operator>>(
        mrpt::utils::CStream& in, CPolyhedron::TPolyhedronEdge& o);
/**
  * Writes a polyhedron edge to a binary stream.
  */
mrpt::utils::CStream& operator<<(
        mrpt::utils::CStream& out, const CPolyhedron::TPolyhedronEdge& o);
/**
  * Reads a polyhedron face from a binary stream.
  */
mrpt::utils::CStream& operator>>(
        mrpt::utils::CStream& in, CPolyhedron::TPolyhedronFace& o);
/**
  * Writes a polyhedron face to a binary stream.
  */
mrpt::utils::CStream& operator<<(
        mrpt::utils::CStream& out, const CPolyhedron::TPolyhedronFace& o);
}
namespace utils
{
// Specialization must occur in the same namespace
MRPT_DECLARE_TTYPENAME_NAMESPACE(CPolyhedron::TPolyhedronEdge, mrpt::opengl)
MRPT_DECLARE_TTYPENAME_NAMESPACE(CPolyhedron::TPolyhedronFace, mrpt::opengl)
}
}
#endif