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.
The basic layout of an entry in the object file is the following:
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 | # 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 | |
The data are the x,y,z (coordinates) for each point. There must be 3*number numerical values.
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.
The data are the x,y,z (coordinates) for each vertex in the polyline. There must be 3*number numerical values.
The data are the x,y,z, r,g,b (coordinates and RGB values) for each vertex in the polyline. There must be 6*number numerical values. The colour changes continuously from one vertex to the next. In the current implementation, the colour is constant for each line segment for the PostScript and Raster3D output modes.
A triangle object may contain 3*N vertices, in which case N triangles are created.
The data are the x,y,z (coordinates) for each vertex in the triangles. There must be 3*number numerical values.
The data are the x,y,z, r,g,b (coordinates and RGB values) for each vertex in the triangles. There must be 6*number numerical values. The colour changes continuously from one vertex to the next. In the current implementation, the colour is constant within each triangle for the PostScript output mode.
The data are x,y,z, nx,ny,nz (coordinates and normal vector coordinates) for each vertex in the triangles. There must be 6*number numerical values. Gouraud shading is used, except for the PostScript output mode.
The data are x,y,z, nx,ny,nz, r,g,b (coordinates, normal vector coordinates and RGB values) for each vertex in the triangles. There must be 9*number numerical values. The colour changes continuously and Gouraud shading is used, except for the PostScript output mode.
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.
The data are the x,y,z (coordinates) for each vertex in the triangles of the strip. There must be 3*number numerical values.
The data are the x,y,z, r,g,b (coordinates and RGB values) for each vertex in the triangles of the strip. There must be 6*number numerical values. The colour changes continuously from one vertex to the next. In the current implementation, the colour is constant within each triangle for the PostScript output mode.
The data are x,y,z, nx,ny,nz (coordinates and normal vector coordinates) for each vertex in the triangles of the strip. There must be 6*number numerical values. Gouraud shading is used, except for the PostScript output mode.
The data are x,y,z, nx,ny,nz, r,g,b (coordinates, normal vector coordinates and RGB values) for each vertex in the triangles of the strip. There must be 9*number numerical values. The colour changes continuously and Gouraud shading is used, except for the PostScript output mode.
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.
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:
Top pageTC 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