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.
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 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
|
# 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
|
Points
- code P: coordinates only
The 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.
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.
- code L: coordinates only
The data are the x,y,z (coordinates) for each vertex in the
polyline. There must be 3*number numerical values.
- code LC: with colours
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.
Triangles
A triangle object may contain 3*N vertices, in which case N triangles
are created.
- code T: coordinates only
The data are the x,y,z (coordinates) for each vertex in the
triangles. There must be 3*number numerical values.
- code TC: with colours
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.
- code TN: with normals
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.
- code TNC: with normals and colours
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
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 only
The 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 colours
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.
- code SN: with normals
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.
- code SNC: with normals and colours
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.
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.
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