The Build Input File Format

 

Like the Curve description files the Build files start with the Time-Object part containing the task, frame and parameter data. Additionally the Build files contain the data for the points the surface patches are build from and for the patches themselves. The format used to describe the points and patches is quite complex therefore we first explain it before presenting the complete examples in the next section.

Points are defined by three coordinate functions (the time t and the int and double parameter can be used for them, see 8.2.2.1) and three int flags, one for each function:

xflag; yflag; zflag;   xfunction; yfunction; zfunction;

If a flag is 0 nothing special happens, when the function is read it is compiled with the function compiler (see 10.2.8) and later evaluated during the computation of the surface. But if some other value is given a ruler is added to the option menu and the corresponding function is used to create an initial spline for it, this way you can edit the point interactively.

The interesting point is that coordinates with identical non-zero flags are connected to the same ruler, therefore they can be edited simultaneously. As an example we use the points of the CLP example in the next section:

# ruler flags / point coordinates
0; 0; 0;       0.0;     0.0;     0.0;
1; 0; 0;   0.5 + t;     0.0;     0.0;
1; 2; 0;   0.5 + t; 0.5 + t;     0.0;
0; 2; 0;       0.0; 0.5 + t;     0.0;
0; 0; 3;       0.0;     0.0; 1.5 - t;
1; 0; 3;   0.5 + t;     0.0; 1.5 - t;

Each line contains the data for one of the six points, only the time t is used in this example. Three rulers will be created, one for the x-coordinates of points 1, 2 and 5, one for the y-coordinates of points 2 and 3 and one for the z-coordinates of points 4 and 5 (points are numbered from 0 as arrays in C).

The function corresponding to a non-zero flag is only evaluated when the flag value is encountered for the first time, otherwise it is just read as a string and discarded. Therefore we could also use the line

1; 2; 0;   ruler; 0.5 + t; 0.0;

for point 2 of the example since the ruler for the flag value 1 was already created from the x-coordinate of point 1.

Patches are defined by their vertices, the boundary curves connecting them and some triangulation information. There are many options, but if you only need straight boundary lines connecting the vertices the format is simple:

orient; 0; type;   v0; v1; v2; [v3;]   ulines; vlines; usub; vsub;

The values v0 upto v3 are the indices of the vertices in the point list, the type can be either 4 for a quadrilateral patch or 3 for a triangular patch (in this case v3 is missing). ulines is the number of points in the direction of the boundary between the points v0 and v1, usub is the number of additional points between each two neighbours of the ulines points. The value vlines and vsub are only evaluated for quadrilateral patches (but they always have to be present), they define the numbers of points in the other direction.

The method "assign-cons-send" computes parameter lines only for the ulines/vlines lines but not for those added by usub/vsub, this allows to define a grid with parameter lines on a sub-grid. This is more interesting for Explicit and Amandus instances where parameter lines make sense, for Surface_Build instances they would be destroyed by the refine methods and especially by "mollify-send" and "equiangulate-send" (compare 8.2.7) therefore by default they are not computed.

For the CLP example we have two quadrilateral patches (0, 1, 2, 3) and (1, 0, 4, 5) with a basic triangulation, the resulting surface family is shown in figure 8.18:

# flag, bnd type, patch type / point indices / u- and v-lines, sub-points
0; 0; 4;   0; 1; 2; 3;   7; 7; 0; 0;
0; 0; 4;   1; 0; 4; 5;   7; 7; 0; 0;

For common boundary lines of the patches -- in this case the line from point 0 to point 1 -- the number of points have to be identical otherwise it is not possible to merge and close the patches to create a single surface.

The orientation of the triangles of a patch and therefore the direction of the surface normal is induced by the orientation of the patch, i.e. the order of its vertices. The orientation of a patch can be changed either by setting the orient flag to a non-zero value or by reversing the order of the points.

Merging and especially closing patches with different orientations can cause severe problems or even crashes since some methods rely on the correct orientation of the triangles. Therefore the common boundary line of two patches should have different (global) orientations for both patches -- as the common line in the CLP example which runs from point 0 to point 1 in the first patch and in the other direction in the second patch. If you are not sure whether the patches of you surface have the correct orientation you should use the display method "normals-disp" to check the surface normals.

Sometimes it is impossible to orientate all patches in the same way (for example for non-orientable surfaces or if more than two patches meet in a common line), in this case you have to be very careful which methods you use. "close-send" and the minimization algorithms of the Dual project (see 8.2.7) are able to handle these surfaces, but methods like "equiangulate-send", "mollify-send" and the refine methods which rely on the neighbour information of the Geom2d instances will get you into trouble.

Additional to straight lines other types of curves can be used to connect the vertices of a patch, in this case the zero between orient and type has to be replaced by a non-zero value and for each boundary the type has to be specified:

orient; 1; type;   v0; v1; v2; [v3;]   ulines; vlines; usub; vsub;
   type0; 0; [ind00; ind01;]
   type1; 0; [ind10; ind11;]
   type2; 0; [ind20; ind21;]
  [type3; 0; [ind30; ind31;]]

The first additional line describes the curve from v0 to v1, the second the one from v1 to v2 and so on, in case of a triangular patch the last line is missing (as v3). The curve types have to specified as octal values:

00200

- The two vertices are connected with a straight line. The value following the type is currently not used and must be zero for all types, for straight lines the two values ind?0 and ind?1 are missing.

00400

- A circle is used to connect the vertices. Like for the following types the two integer values ind?0 and ind?1 refer to the point list, in this case ind?0 is the index of the midpoint of the circle and ind?1 the one of the normal of the circle plane. As usual the variables can be used to define the midpoint and the normal, and their coordinates can be bound to rulers to edit them interactively.

01000

- Connect the vertices with a helix. ind?0 and ind?1 are the two points on the axis of the helix with the same heights (with respect to the axis) as the vertices, i.e. ind?0 must be in the plane orthogonal to the axis through the start vertex of the helix and ind?1 in that one through the end vertex with the same normal.

02000

- Use a spline to connect the vertices. The ind?0 and ind?1 values refer to the tangent vectors at the start and the end vertex of the spline.

For some applications, for example for the minimization algorithms of the Dual project (see 8.2.7) and the refine methods, it is necessary to define restrictions for the boundary curves. This is what the lower bits of the type field are reserved for:

00004

- Restrict the points of the curve to a circle (of course this value can only be used for circular curves of type 00400), currently this value is only used by the refine methods.

00010

- All points of the boundary curve are fixed. This is the default for most methods if no restriction is given, but some methods detect automatically whether a curve is straight or planar if no restriction is given therefore this value should be set if you want to make sure that the points of a straight or planar curve remain fixed.

00020

- The points of a boundary curve are restricted to a straight line, this is only possible for straight curves with type 00200. This value isn't really needed at the moment (new points inserted by refine are already on the curve and the minimization methods detect straight lines) but it should be set anyway.

00040

- Restrict the points of the boundary curve to a plane. Currently the plane is computed from the curve data, therefore this value can only be used for circular curves of type 00400 and for spline curves of type 02000 if they are planar.

Some example *.bd input files which use these curve types can be found in the demo directory of the GRAPE distribution, one of them is presented in the next section.