2
/**************************************************************************
4
* Regina - A Normal Surface Theory Calculator *
5
* Computational Engine *
7
* Copyright (c) 1999-2013, Ben Burton *
8
* For further details contact Ben Burton (bab@debian.org). *
10
* This program is free software; you can redistribute it and/or *
11
* modify it under the terms of the GNU General Public License as *
12
* published by the Free Software Foundation; either version 2 of the *
13
* License, or (at your option) any later version. *
15
* As an exception, when this program is distributed through (i) the *
16
* App Store by Apple Inc.; (ii) the Mac App Store by Apple Inc.; or *
17
* (iii) Google Play by Google Inc., then that store may impose any *
18
* digital rights management, device limits and/or redistribution *
19
* restrictions that are required by its terms of service. *
21
* This program is distributed in the hope that it will be useful, but *
22
* WITHOUT ANY WARRANTY; without even the implied warranty of *
23
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU *
24
* General Public License for more details. *
26
* You should have received a copy of the GNU General Public *
27
* License along with this program; if not, write to the Free *
28
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, *
29
* MA 02110-1301, USA. *
31
**************************************************************************/
35
/*! \file triangulation/ntriangle.h
36
* \brief Deals with triangles in a triangulation.
44
#include "regina-core.h"
45
#include "shareableobject.h"
46
#include "maths/nperm4.h"
47
#include "utilities/nmarkedvector.h"
48
// NOTE: More #includes follow after the class declarations.
52
class NBoundaryComponent;
60
* \weakgroup triangulation
65
* Details how a triangle in the skeleton forms part of an individual
68
class REGINA_API NTriangleEmbedding {
70
NTetrahedron* tetrahedron_;
71
/**< The tetrahedron in which this triangle is contained. */
73
/**< The face number of the tetrahedron that is this triangle. */
77
* Creates an embedding descriptor containing the given data.
79
* @param tet the tetrahedron in which this triangle is contained.
80
* @param tri the face number of \a tet that is this triangle.
82
NTriangleEmbedding(NTetrahedron* tet, int tri);
85
* Creates an embedding descriptor containing the same data as
86
* the given embedding descriptor.
88
* @param cloneMe the embedding descriptor to clone.
90
NTriangleEmbedding(const NTriangleEmbedding& cloneMe);
93
* Returns the tetrahedron in which this triangle is contained.
95
* @return the tetrahedron.
97
NTetrahedron* getTetrahedron() const;
100
* Returns the triangle number within getTetrahedron() that is
103
* @return the triangle number that is this triangle.
105
int getTriangle() const;
107
* A deprecated alias for getTriangle().
109
* This routine returns the triangle number within getTetrahedron()
110
* that is this triangle. See getTriangle() for further details.
112
* \deprecated This routine will be removed in a future version
113
* of Regina. Please use getTriangle() instead.
115
* @return the triangle number that is this triangle.
120
* Returns a mapping from vertices (0,1,2) of this triangle to the
121
* corresponding vertex numbers in getTetrahedron(), as described
122
* in NTetrahedron::getTriangleMapping().
124
* @return a mapping from the vertices of this triangle to the
125
* vertices of getTetrahedron().
127
NPerm4 getVertices() const;
131
* Represents a triangle in the skeleton of a triangulation.
132
* Triangles are highly temporary; once a triangulation changes, all its
133
* triangle objects will be deleted and new ones will be created.
135
class REGINA_API NTriangle : public ShareableObject, public NMarkedElement {
137
static const int TRIANGLE;
138
/**< Specifies a triangle with no identified vertices or edges. */
139
static const int SCARF;
140
/**< Specifies a triangle with two identified vertices. */
141
static const int PARACHUTE;
142
/**< Specifies a triangle with three identified vertices. */
143
static const int CONE;
144
/**< Specifies a triangle with two edges identified to form a
146
static const int MOBIUS;
147
/**< Specifies a triangle with two edges identified to form a
149
static const int HORN;
150
/**< Specifies a triangle with two edges identified to form a
151
cone with all three vertices identified. */
152
static const int DUNCEHAT;
153
/**< Specifies a triangle with all three edges identified, some
154
via orientable and some via non-orientable gluings. */
155
static const int L31;
156
/**< Specifies a triangle with all three edges identified using
157
non-orientable gluings. Note that this forms a spine for
158
the Lens space L(3,1). */
161
* An array that maps triangle numbers within a tetrahedron
162
* (i.e., face numbers) to the canonical ordering of the individual
163
* tetrahedron vertices that form each triangle.
165
* This means that the vertices of triangle \a i in a tetrahedron
166
* are, in canonical order, <tt>ordering[i][0..2]</tt>. As an
167
* immediate consequence, we obtain <tt>ordering[i][3] == i</tt>.
169
* Regina defines canonical order to be \e increasing order.
170
* That is, <tt>ordering[i][0] < ... < ordering[i][2]</tt>.
172
* This table does \e not describe the mapping from specific
173
* triangles within a triangulation into individual tetrahedra (for
174
* that, see NTetrahedron::getTriangleMapping() instead). This table
175
* merely provides a neat and consistent way of listing the
176
* vertices of any given tetrahedron face.
178
* This lookup table replaces the deprecated routine
179
* regina::faceOrdering().
181
static const NPerm4 ordering[4];
184
NTriangleEmbedding* embeddings[2];
185
/**< An array of descriptors telling how this triangle forms a
186
part of each individual tetrahedron that it belongs to.
187
These embeddings will be automatically deleted when the
188
triangle itself is deleted. */
190
/**< The number of embedding descriptors stored in
191
the embeddings array. */
192
NComponent* component;
193
/**< The component that this triangle is a part of. */
194
NBoundaryComponent* boundaryComponent;
195
/**< The boundary component that this triangle is a part of,
196
or 0 if this triangle is internal. */
198
/**< Specifies the triangle type according to one of the
199
predefined triangle type constants in NTriangle, or 0 if
200
type has not yet been determined. */
202
/**< Specifies the vertex or edge that plays a special role
203
for the triangle type specified by \a type. This is only
204
relevant for some triangle types. */
208
* Default destructor.
209
* All embedding descriptors stored in this triangle will be
210
* automatically deleted.
212
virtual ~NTriangle();
215
* Determines if this triangle lies entirely on the boundary of the
218
* @return \c true if and only if this triangle lies on the boundary.
220
bool isBoundary() const;
223
* Returns a description of the triangle type.
224
* The triangle type describes how the edges and vertices of the
225
* triangle are identified.
227
* @return one of the predefined triangle type constants in NTriangle.
232
* Return the triangle vertex or triangle edge that plays a special role
233
* for the triangle type of this triangle. Note that this routine is
234
* only relevant for some triangle types. The triangle type is
235
* returned by getType().
237
* @return The vertex or edge that plays a special role (this
238
* will be 0, 1 or 2), or -1 if this triangle type has no special
244
* Determines whether this triangle is wrapped up to form a Mobius band.
246
* Note that several different triangle types (as returned by
247
* getType()) can produce this result.
248
* Note also that a triangle can be both a Mobius band \a and a cone.
250
* @return \c true if and only if this triangle is a Mobius band.
255
* Determines whether this triangle is wrapped up to form a cone.
257
* Note that several different triangle types (as returned by
258
* getType()) can produce this result.
259
* Note also that a triangle can be both a Mobius band \a and a cone.
261
* @return \c true if and only if this triangle is a cone.
266
* Returns the number of descriptors available through getEmbedding().
267
* Note that this number will never be greater than two.
269
* @return the number of embedding descriptors.
271
unsigned getNumberOfEmbeddings() const;
274
* Returns the requested descriptor detailing how this triangle forms a
275
* part of a particular tetrahedron in the triangulation.
276
* Note that if this triangle represents multiple faces of a
277
* particular tetrahedron, then there will be multiple embedding
278
* descriptors available regarding that tetrahedron.
280
* @param index the index of the requested descriptor. This
281
* should be between 0 and getNumberOfEmbeddings()-1 inclusive.
282
* @return the requested embedding descriptor.
284
const NTriangleEmbedding& getEmbedding(unsigned index) const;
287
* Returns the triangulation to which this triangle belongs.
289
* @return the triangulation containing this triangle.
291
NTriangulation* getTriangulation() const;
294
* Returns the component of the triangulation to which this
297
* @return the component containing this triangle.
299
NComponent* getComponent() const;
302
* Returns the boundary component of the triangulation to which
303
* this triangle belongs.
305
* @return the boundary component containing this triangle, or 0 if this
306
* triangle does not lie entirely within the boundary of the
309
NBoundaryComponent* getBoundaryComponent() const;
312
* Returns the vertex of the triangulation that corresponds
313
* to the given vertex of this triangle.
315
* Note that vertex \a i of a triangle is opposite edge \a i of the
318
* @param vertex the vertex of this triangle to examine. This should
320
* @return the corresponding vertex of the triangulation.
322
NVertex* getVertex(int vertex) const;
324
* Returns the edge of the triangulation that corresponds
325
* to the given edge of this triangle.
327
* Note that edge \a i of a triangle is opposite vertex \a i of the
330
* @param edge the edge of this triangle to examine. This should be
332
* @return the corresponding edge of the triangulation.
334
NEdge* getEdge(int edge) const;
336
* Examines the given edge of this triangle, and returns a mapping
337
* from the "canonical" vertices of the corresponding edge of
338
* the triangulation to the vertices of this triangle.
340
* This routine behaves much the same as
341
* NTetrahedron::getEdgeMapping(), except that it maps the edge
342
* vertices into a triangle, not into a tetrahedron. See
343
* NTetrahedron::getEdgeMapping() for a more detailed
344
* explanation of precisely what this mapping means.
346
* This routine differs from NTetrahedron::getEdgeMapping() in
347
* how it handles the images of 2 and 3. This routine will
348
* always map 2 to the remaining vertex of this triangle (which is
349
* equal to the argument \a edge), and will always map 3 to itself.
351
* @param edge the edge of this triangle to examine. This should be
353
* @return a mapping from vertices (0,1) of the requested edge to
354
* the vertices of this triangle.
356
NPerm4 getEdgeMapping(int edge) const;
358
void writeTextShort(std::ostream& out) const;
359
void writeTextLong(std::ostream& out) const;
363
* Creates a new triangle and marks it as belonging to the
364
* given triangulation component.
366
* @param myComponent the triangulation component to which this
369
NTriangle(NComponent* myComponent);
371
friend class NTriangulation;
372
/**< Allow access to private members. */
377
} // namespace regina
378
// Some more headers that are required for inline functions:
379
#include "triangulation/ntetrahedron.h"
382
// Inline functions for NTriangle
384
inline NTriangle::NTriangle(NComponent* myComponent) : nEmbeddings(0),
385
component(myComponent), boundaryComponent(0), type(0) {
388
inline NTriangle::~NTriangle() {
390
delete embeddings[0];
392
delete embeddings[1];
395
inline NTriangulation* NTriangle::getTriangulation() const {
396
return embeddings[0]->getTetrahedron()->getTriangulation();
399
inline NComponent* NTriangle::getComponent() const {
403
inline NBoundaryComponent* NTriangle::getBoundaryComponent() const {
404
return boundaryComponent;
407
inline NVertex* NTriangle::getVertex(int vertex) const {
408
return embeddings[0]->getTetrahedron()->getVertex(
409
embeddings[0]->getVertices()[vertex]);
412
inline bool NTriangle::isBoundary() const {
413
return (boundaryComponent != 0);
416
inline int NTriangle::getSubtype() {
421
inline bool NTriangle::isMobiusBand() {
423
return (type == L31 || type == DUNCEHAT || type == MOBIUS);
426
inline bool NTriangle::isCone() {
428
return (type == DUNCEHAT || type == CONE || type == HORN);
431
inline unsigned NTriangle::getNumberOfEmbeddings() const {
435
inline const NTriangleEmbedding& NTriangle::getEmbedding(unsigned index) const {
436
return *(embeddings[index]);
439
inline void NTriangle::writeTextShort(std::ostream& out) const {
440
out << (isBoundary() ? "Boundary " : "Internal ") << "triangle";
443
inline NTriangleEmbedding::NTriangleEmbedding(NTetrahedron* tet, int tri) :
444
tetrahedron_(tet), tri_(tri) {
447
inline NTriangleEmbedding::NTriangleEmbedding(
448
const NTriangleEmbedding& cloneMe) :
449
tetrahedron_(cloneMe.tetrahedron_), tri_(cloneMe.tri_) {
452
inline NTetrahedron* NTriangleEmbedding::getTetrahedron() const {
456
inline int NTriangleEmbedding::getTriangle() const {
460
inline int NTriangleEmbedding::getFace() const {
464
inline NPerm4 NTriangleEmbedding::getVertices() const {
465
return tetrahedron_->getTriangleMapping(tri_);
468
} // namespace regina