Logo ROOT   6.16/01
Reference Guide
triangle.h
Go to the documentation of this file.
1#ifndef TRIANGLE_H
2#define TRIANGLE_H
3
4/*****************************************************************************/
5/* */
6/* (triangle.h) */
7/* */
8/* Include file for programs that call Triangle. */
9/* */
10/* Accompanies Triangle Version 1.6 */
11/* July 28, 2005 */
12/* */
13/* Copyright 1996, 2005 */
14/* Jonathan Richard Shewchuk */
15/* 2360 Woolsey #H */
16/* Berkeley, California 94705-1927 */
17/* jrs@cs.berkeley.edu */
18/* */
19/*****************************************************************************/
20
21/*****************************************************************************/
22/* */
23/* How to call Triangle from another program */
24/* */
25/* */
26/* If you haven't read Triangle's instructions (run "triangle -h" to read */
27/* them), you won't understand what follows. */
28/* */
29/* Triangle must be compiled into an object file (triangle.o) with the */
30/* TRILIBRARY symbol defined (generally by using the -DTRILIBRARY compiler */
31/* switch). The makefile included with Triangle will do this for you if */
32/* you run "make trilibrary". The resulting object file can be called via */
33/* the procedure triangulate(). */
34/* */
35/* If the size of the object file is important to you, you may wish to */
36/* generate a reduced version of triangle.o. The REDUCED symbol gets rid */
37/* of all features that are primarily of research interest. Specifically, */
38/* the -DREDUCED switch eliminates Triangle's -i, -F, -s, and -C switches. */
39/* The CDT_ONLY symbol gets rid of all meshing algorithms above and beyond */
40/* constrained Delaunay triangulation. Specifically, the -DCDT_ONLY switch */
41/* eliminates Triangle's -r, -q, -a, -u, -D, -Y, -S, and -s switches. */
42/* */
43/* IMPORTANT: These definitions (TRILIBRARY, REDUCED, CDT_ONLY) must be */
44/* made in the makefile or in triangle.c itself. Putting these definitions */
45/* in this file (triangle.h) will not create the desired effect. */
46/* */
47/* */
48/* The calling convention for triangulate() follows. */
49/* */
50/* void triangulate(triswitches, in, out, vorout) */
51/* char *triswitches; */
52/* struct triangulateio *in; */
53/* struct triangulateio *out; */
54/* struct triangulateio *vorout; */
55/* */
56/* `triswitches' is a string containing the command line switches you wish */
57/* to invoke. No initial dash is required. Some suggestions: */
58/* */
59/* - You'll probably find it convenient to use the `z' switch so that */
60/* points (and other items) are numbered from zero. This simplifies */
61/* indexing, because the first item of any type always starts at index */
62/* [0] of the corresponding array, whether that item's number is zero or */
63/* one. */
64/* - You'll probably want to use the `Q' (quiet) switch in your final code, */
65/* but you can take advantage of Triangle's printed output (including the */
66/* `V' switch) while debugging. */
67/* - If you are not using the `q', `a', `u', `D', `j', or `s' switches, */
68/* then the output points will be identical to the input points, except */
69/* possibly for the boundary markers. If you don't need the boundary */
70/* markers, you should use the `N' (no nodes output) switch to save */
71/* memory. (If you do need boundary markers, but need to save memory, a */
72/* good nasty trick is to set out->pointlist equal to in->pointlist */
73/* before calling triangulate(), so that Triangle overwrites the input */
74/* points with identical copies.) */
75/* - The `I' (no iteration numbers) and `g' (.off file output) switches */
76/* have no effect when Triangle is compiled with TRILIBRARY defined. */
77/* */
78/* `in', `out', and `vorout' are descriptions of the input, the output, */
79/* and the Voronoi output. If the `v' (Voronoi output) switch is not used, */
80/* `vorout' may be NULL. `in' and `out' may never be NULL. */
81/* */
82/* Certain fields of the input and output structures must be initialized, */
83/* as described below. */
84/* */
85/*****************************************************************************/
86
87/*****************************************************************************/
88/* */
89/* The `triangulateio' structure. */
90/* */
91/* Used to pass data into and out of the triangulate() procedure. */
92/* */
93/* */
94/* Arrays are used to store points, triangles, markers, and so forth. In */
95/* all cases, the first item in any array is stored starting at index [0]. */
96/* However, that item is item number `1' unless the `z' switch is used, in */
97/* which case it is item number `0'. Hence, you may find it easier to */
98/* index points (and triangles in the neighbor list) if you use the `z' */
99/* switch. Unless, of course, you're calling Triangle from a Fortran */
100/* program. */
101/* */
102/* Description of fields (except the `numberof' fields, which are obvious): */
103/* */
104/* `pointlist': An array of point coordinates. The first point's x */
105/* coordinate is at index [0] and its y coordinate at index [1], followed */
106/* by the coordinates of the remaining points. Each point occupies two */
107/* REALs. */
108/* `pointattributelist': An array of point attributes. Each point's */
109/* attributes occupy `numberofpointattributes' REALs. */
110/* `pointmarkerlist': An array of point markers; one int per point. */
111/* */
112/* `trianglelist': An array of triangle corners. The first triangle's */
113/* first corner is at index [0], followed by its other two corners in */
114/* counterclockwise order, followed by any other nodes if the triangle */
115/* represents a nonlinear element. Each triangle occupies */
116/* `numberofcorners' ints. */
117/* `triangleattributelist': An array of triangle attributes. Each */
118/* triangle's attributes occupy `numberoftriangleattributes' REALs. */
119/* `trianglearealist': An array of triangle area constraints; one REAL per */
120/* triangle. Input only. */
121/* `neighborlist': An array of triangle neighbors; three ints per */
122/* triangle. Output only. */
123/* */
124/* `segmentlist': An array of segment endpoints. The first segment's */
125/* endpoints are at indices [0] and [1], followed by the remaining */
126/* segments. Two ints per segment. */
127/* `segmentmarkerlist': An array of segment markers; one int per segment. */
128/* */
129/* `holelist': An array of holes. The first hole's x and y coordinates */
130/* are at indices [0] and [1], followed by the remaining holes. Two */
131/* REALs per hole. Input only, although the pointer is copied to the */
132/* output structure for your convenience. */
133/* */
134/* `regionlist': An array of regional attributes and area constraints. */
135/* The first constraint's x and y coordinates are at indices [0] and [1], */
136/* followed by the regional attribute at index [2], followed by the */
137/* maximum area at index [3], followed by the remaining area constraints. */
138/* Four REALs per area constraint. Note that each regional attribute is */
139/* used only if you select the `A' switch, and each area constraint is */
140/* used only if you select the `a' switch (with no number following), but */
141/* omitting one of these switches does not change the memory layout. */
142/* Input only, although the pointer is copied to the output structure for */
143/* your convenience. */
144/* */
145/* `edgelist': An array of edge endpoints. The first edge's endpoints are */
146/* at indices [0] and [1], followed by the remaining edges. Two ints per */
147/* edge. Output only. */
148/* `edgemarkerlist': An array of edge markers; one int per edge. Output */
149/* only. */
150/* `normlist': An array of normal vectors, used for infinite rays in */
151/* Voronoi diagrams. The first normal vector's x and y magnitudes are */
152/* at indices [0] and [1], followed by the remaining vectors. For each */
153/* finite edge in a Voronoi diagram, the normal vector written is the */
154/* zero vector. Two REALs per edge. Output only. */
155/* */
156/* */
157/* Any input fields that Triangle will examine must be initialized. */
158/* Furthermore, for each output array that Triangle will write to, you */
159/* must either provide space by setting the appropriate pointer to point */
160/* to the space you want the data written to, or you must initialize the */
161/* pointer to NULL, which tells Triangle to allocate space for the results. */
162/* The latter option is preferable, because Triangle always knows exactly */
163/* how much space to allocate. The former option is provided mainly for */
164/* people who need to call Triangle from Fortran code, though it also makes */
165/* possible some nasty space-saving tricks, like writing the output to the */
166/* same arrays as the input. */
167/* */
168/* Triangle will not free() any input or output arrays, including those it */
169/* allocates itself; that's up to you. You should free arrays allocated by */
170/* Triangle by calling the trifree() procedure defined below. (By default, */
171/* trifree() just calls the standard free() library procedure, but */
172/* applications that call triangulate() may replace trimalloc() and */
173/* trifree() in triangle.c to use specialized memory allocators.) */
174/* */
175/* Here's a guide to help you decide which fields you must initialize */
176/* before you call triangulate(). */
177/* */
178/* `in': */
179/* */
180/* - `pointlist' must always point to a list of points; `numberofpoints' */
181/* and `numberofpointattributes' must be properly set. */
182/* `pointmarkerlist' must either be set to NULL (in which case all */
183/* markers default to zero), or must point to a list of markers. If */
184/* `numberofpointattributes' is not zero, `pointattributelist' must */
185/* point to a list of point attributes. */
186/* - If the `r' switch is used, `trianglelist' must point to a list of */
187/* triangles, and `numberoftriangles', `numberofcorners', and */
188/* `numberoftriangleattributes' must be properly set. If */
189/* `numberoftriangleattributes' is not zero, `triangleattributelist' */
190/* must point to a list of triangle attributes. If the `a' switch is */
191/* used (with no number following), `trianglearealist' must point to a */
192/* list of triangle area constraints. `neighborlist' may be ignored. */
193/* - If the `p' switch is used, `segmentlist' must point to a list of */
194/* segments, `numberofsegments' must be properly set, and */
195/* `segmentmarkerlist' must either be set to NULL (in which case all */
196/* markers default to zero), or must point to a list of markers. */
197/* - If the `p' switch is used without the `r' switch, then */
198/* `numberofholes' and `numberofregions' must be properly set. If */
199/* `numberofholes' is not zero, `holelist' must point to a list of */
200/* holes. If `numberofregions' is not zero, `regionlist' must point to */
201/* a list of region constraints. */
202/* - If the `p' switch is used, `holelist', `numberofholes', */
203/* `regionlist', and `numberofregions' is copied to `out'. (You can */
204/* nonetheless get away with not initializing them if the `r' switch is */
205/* used.) */
206/* - `edgelist', `edgemarkerlist', `normlist', and `numberofedges' may be */
207/* ignored. */
208/* */
209/* `out': */
210/* */
211/* - `pointlist' must be initialized (NULL or pointing to memory) unless */
212/* the `N' switch is used. `pointmarkerlist' must be initialized */
213/* unless the `N' or `B' switch is used. If `N' is not used and */
214/* `in->numberofpointattributes' is not zero, `pointattributelist' must */
215/* be initialized. */
216/* - `trianglelist' must be initialized unless the `E' switch is used. */
217/* `neighborlist' must be initialized if the `n' switch is used. If */
218/* the `E' switch is not used and (`in->numberofelementattributes' is */
219/* not zero or the `A' switch is used), `elementattributelist' must be */
220/* initialized. `trianglearealist' may be ignored. */
221/* - `segmentlist' must be initialized if the `p' or `c' switch is used, */
222/* and the `P' switch is not used. `segmentmarkerlist' must also be */
223/* initialized under these circumstances unless the `B' switch is used. */
224/* - `edgelist' must be initialized if the `e' switch is used. */
225/* `edgemarkerlist' must be initialized if the `e' switch is used and */
226/* the `B' switch is not. */
227/* - `holelist', `regionlist', `normlist', and all scalars may be ignored.*/
228/* */
229/* `vorout' (only needed if `v' switch is used): */
230/* */
231/* - `pointlist' must be initialized. If `in->numberofpointattributes' */
232/* is not zero, `pointattributelist' must be initialized. */
233/* `pointmarkerlist' may be ignored. */
234/* - `edgelist' and `normlist' must both be initialized. */
235/* `edgemarkerlist' may be ignored. */
236/* - Everything else may be ignored. */
237/* */
238/* After a call to triangulate(), the valid fields of `out' and `vorout' */
239/* will depend, in an obvious way, on the choice of switches used. Note */
240/* that when the `p' switch is used, the pointers `holelist' and */
241/* `regionlist' are copied from `in' to `out', but no new space is */
242/* allocated; be careful that you don't free() the same array twice. On */
243/* the other hand, Triangle will never copy the `pointlist' pointer (or any */
244/* others); new space is allocated for `out->pointlist', or if the `N' */
245/* switch is used, `out->pointlist' remains uninitialized. */
246/* */
247/* All of the meaningful `numberof' fields will be properly set; for */
248/* instance, `numberofedges' will represent the number of edges in the */
249/* triangulation whether or not the edges were written. If segments are */
250/* not used, `numberofsegments' will indicate the number of boundary edges. */
251/* */
252/*****************************************************************************/
253
254#ifdef __cplusplus
255extern "C" {
256#endif
257
258/* For single precision (which will save some memory and reduce paging), */
259/* define the symbol SINGLE by using the -DSINGLE compiler switch or by */
260/* writing "#define SINGLE" below. */
261/* */
262/* For double precision (which will allow you to refine meshes to a smaller */
263/* edge length), leave SINGLE undefined. */
264/* */
265/* Double precision uses more memory, but improves the resolution of the */
266/* meshes you can generate with Triangle. It also reduces the likelihood */
267/* of a floating exception due to overflow. Finally, it is much faster */
268/* than single precision on 64-bit architectures like the DEC Alpha. I */
269/* recommend double precision unless you want to generate a mesh for which */
270/* you do not have enough memory. */
271
272/* #define SINGLE */
273
274#ifdef SINGLE
275#define REAL float
276#else /* not SINGLE */
277#define REAL double
278#endif /* not SINGLE */
279
280#define ANSI_DECLARATORS
281
282/* The next line is used to outsmart some very stupid compilers. If your */
283/* compiler is smarter, feel free to replace the "int" with "void". */
284/* Not that it matters. */
285
286#define VOID void
287
289 REAL *pointlist; /* In / out */
290 REAL *pointattributelist; /* In / out */
291 int *pointmarkerlist; /* In / out */
292 int numberofpoints; /* In / out */
293 int numberofpointattributes; /* In / out */
294
295 int *trianglelist; /* In / out */
297 REAL *trianglearealist; /* In only */
298 int *neighborlist; /* Out only */
299 int numberoftriangles; /* In / out */
300 int numberofcorners; /* In / out */
301 int numberoftriangleattributes; /* In / out */
302
303 int *segmentlist; /* In / out */
304 int *segmentmarkerlist; /* In / out */
305 int numberofsegments; /* In / out */
306
307 REAL *holelist; /* In / pointer to array copied out */
308 int numberofholes; /* In / copied out */
309
310 REAL *regionlist; /* In / pointer to array copied out */
311 int numberofregions; /* In / copied out */
312
313 int *edgelist; /* Out only */
314 int *edgemarkerlist; /* Not used with Voronoi diagram; out only */
315 REAL *normlist; /* Used only with Voronoi diagram; out only */
316 int numberofedges; /* Out only */
317};
318
319#ifdef ANSI_DECLARATORS
320void triangulate(char *, struct triangulateio *, struct triangulateio *,
321 struct triangulateio *);
322void trifree(VOID *memptr);
323#else /* not ANSI_DECLARATORS */
324void triangulate();
325void trifree();
326#endif /* not ANSI_DECLARATORS */
327
328#ifdef __cplusplus
329}
330#endif
331
332#endif /* not TRIANGLE_H */
REAL * pointattributelist
Definition: triangle.h:290
int * neighborlist
Definition: triangle.h:298
int numberoftriangleattributes
Definition: triangle.h:301
int numberofpoints
Definition: triangle.h:292
int * edgemarkerlist
Definition: triangle.h:314
int numberofsegments
Definition: triangle.h:305
REAL * normlist
Definition: triangle.h:315
int numberoftriangles
Definition: triangle.h:299
REAL * trianglearealist
Definition: triangle.h:297
int * trianglelist
Definition: triangle.h:295
REAL * pointlist
Definition: triangle.h:289
int * segmentmarkerlist
Definition: triangle.h:304
int numberofholes
Definition: triangle.h:308
REAL * regionlist
Definition: triangle.h:310
int numberofpointattributes
Definition: triangle.h:293
int numberofcorners
Definition: triangle.h:300
int numberofregions
Definition: triangle.h:311
int numberofedges
Definition: triangle.h:316
int * pointmarkerlist
Definition: triangle.h:291
int * segmentlist
Definition: triangle.h:303
REAL * triangleattributelist
Definition: triangle.h:296
REAL * holelist
Definition: triangle.h:307
int * edgelist
Definition: triangle.h:313
void trifree(VOID *memptr)
Definition: triangle.c:1414
#define REAL
Definition: triangle.h:277
void triangulate(char *, struct triangulateio *, struct triangulateio *, struct triangulateio *)
Definition: triangle.c:15652
#define VOID
Definition: triangle.h:286