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:

- A code of 1-3 characters (see below) denoting the object type.
- A positive integer value giving the number of vertices in the object.
- The x,y,z coordinates, and normals and/or RGB colour values (if any) for each vertex.

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 |

**code P**: coordinates onlyThe data are the x,y,z (coordinates) for each point. There must be 3*number numerical values.

**code PC**: with colours The data are the x,y,z, r,g,b (coordinates and RGB values) for each point. There must be 6*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.

**code L**: coordinates onlyThe data are the x,y,z (coordinates) for each vertex in the polyline. There must be 3*number numerical values.

**code LC**: with coloursThe 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.

**code T**: coordinates onlyThe data are the x,y,z (coordinates) for each vertex in the triangles. There must be 3*number numerical values.

**code TC**: with coloursThe 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.

**code TN**: with normalsThe 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.

**code TNC**: with normals and coloursThe 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.

**code S**: coordinates onlyThe data are the x,y,z (coordinates) for each vertex in the triangles of the strip. There must be 3*number numerical values.

**code SC**: with coloursThe 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.

**code SN**: with normalsThe 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.

**code SNC**: with normals and coloursThe 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