Object file format

This is a description of the format of the file read by the object command. The file may contain data specifying points, lines, triangles and triangle strip surfaces, with colours and normal vectors optionally specified. This feature is intended as an interface to external programs that produce objects such as surfaces. It should not be too difficult to create scripts or utility programs that convert the original output from such external programs into the file format described here.


General format rules

The basic layout of an entry in the object file is the following:
  1. A code of 1-3 characters (see below) denoting the object type.
  2. A positive integer value giving the number of vertices in the object.
  3. The x,y,z coordinates, and normals and/or RGB colour values (if any) for each vertex.
The file may contain any number and mixture of such entries. It is possible, for instance, to define within one single object file a surface consisting of triangle strips, and a number of points (dots) outside the surface.

The number given after the code denotes the number of vertices in the object, not the number of segments, or anything like that. For lines, the number must be at least 2. For triangles, the number must at least 3 and a multiple of 3. For triangle strips, it must be at least 3. The number of numerical values needed for the object also depends on whether RGB values and/or normal vectors are to be specified for the object.

The file format is free, meaning that the different items (object codes and numerical values) must be separated by white-space characters (space, tab or newline) but otherwise the items may be placed anywhere on a line, or split up between lines. The object file cannot contain any comments. Note that this also the case for an inline object specification within a MolScript input file, which cannot contain the usual type of comment among the object data.

The x,y,z coordinates are in units of Ångström. The RGB component values must be in the range 0.0 to 1.0 (inclusive). The normal vectors must be normalized (i.e. length 1.0).


Object code table

object code # vertices data for each vertex
coordinates normals RGB values
points P >= 1 x,y,z - -
PC >= 1 x,y,z - r,g,b
polyline L >= 2 x,y,z - -
LC >= 2 x,y,z - r,g,b
triangles T >= 3*N x,y,z - -
TC >= 3*N x,y,z - r,g,b
TN >= 3*N x,y,z nx,ny,nz -
TNC >= 3*N x,y,z nx,ny,nz r,g,b
triangle strip S >= 3 x,y,z - -
SC >= 3 x,y,z - r,g,b
SN >= 3 x,y,z nx,ny,nz -
SNC >= 3 x,y,z nx,ny,nz r,g,b


Object codes description

Points

Lines

A line object may contain more than two vertices, in which case it becomes a so-called polyline, where each vertex is connected by a line to the next.

Triangles

A triangle object may contain 3*N vertices, in which case N triangles are created.

Triangle strips

Triangle strips are a more compact way of specifying surfaces consisting of many triangles that share edges. A triangle strip is given by 3 or more vertices, where vertex 1, 2 and 3 form the first triangle, vertices 2, 3 and 4 the next, vertices 3, 4, and 5 the next, and so on.

code Q: End of data

The end-of-data code denotes that there are no more objects in the file. There is no integer value after this code, in contrast to all other codes. MolScript stops reading the object file, closes it, and resumes reading the original MolScript input file. The Q code is necessary when the object file is inlined into the MolScript file. The Q code is not necessary when the object file is external; the ordinary end-of-file is then sufficient.


Examples

Four points in a square around the origin:
P 4
1 0 0
0 1 0
-1 0 0
0 -1 0
Q
A cube around the origin:
L 10
1 1 -1
1 -1 -1
-1 -1 -1
-1 1 -1
1 1 -1
1 1 1
1 -1 1
-1 -1 1
-1 1 1
1 1 1
L 2
1 -1 -1
1 -1 1
L 2  -1 -1 -1  -1 -1 1
L 2  -1 1 -1  -1 1 1
Q
A triangle with specified vertex colours:
TC 3
10 10 0  0.4 1.0 0.0
10 -10 0 1.0 0.4 0.0
-10 0 0  0.0 0.0 1.0
Q


Top page