AMS Specification 2.0
Ascii Mesh Format, MathLive version 2.00
(c)Milo Hedge Limited 1996
Whitespace is a contiguous sequence of newline, space, and tab characters.
Any contiguous sequence of non-whitespace characters, delimited by start-of-file, whitespace or end-of-file is recognised as a token.
Any token beginning with '#' is ignored, together with any tokens up to, but not including, the next newline character.
Any token which starts with the '"' character continues until another '"' followed by whitespace. The closing '"' must be on the same line as the opening '"'.
Any token beginning with '$' is a section name. Sections are followed by a list of items bracketed by '{' and '}' tokens. Sections may be nested at any point. Unrecognised sections are parsed, but the contents are completely ignored (basically, this means that any curly brackets should nest properly).
Recognised Sections
In the following,
k_sometext represents a coefficient (a real
value in the interval [0, 1]).
tn, un, vn, wn represents an integer
vertex index in the range 1 to the number of vertices.
xn, yn, zn are floating-point coordinates.
realn is a floating-point number.
token is a token as described above.
'*' says that the preceding token may be repeated zero or more times.
'+' means the preceding token is optional (i.e., repeated 0 or 1 times).
A group of items separated by '|' represents a choice of one from a list of possibilities.
Literal numbers are in C notation (i.e., 0x3f is an acceptable integer).
Integers are allowed wherever a floating-point number is expected.
> Literal text is in this font.
- $Mesh { ... }
- Encloses a modelling context. The next vertex to be defined will have index 1. Nested meshes are allowed. In MathLive, when a parent mesh moves, its children move with it. Direct manipulation of a child mesh does not change the position of its parent.
- $Comment { Any sequence of tokens }
- A $Comment section is guaranteed to remain unrecognised, and thus will not be acted on by all future versions of the parser. Note that the tokens inside a $Comment section are still parsed and must therefore still nest correctly. Apart from this, their contents are ignored; this allows (possibly) nested sections of a file to be commented out.
- $Transform { real1 real2 ... real16 }
- The 16 elements of a 4 x 4 transformation matrix. If the object under construction is nested inside another, then the transformation is relative to its parent. Before the first $Vertices section in the current mesh (even an empty list of vertices), $Transform affects the local origin of the object under construction. After the appearance of the first $Vertices, the origin is unaffected, and the coordinates of all vertices defined afterwards are affected. In some versions of MathLive, the transform should not contain any rotation (which should be specified by $Orientation below).
- $Orientation { real1 real2 ... real16 }
- The 16 elements of a 4 x 4 transformation matrix. If the object under construction is nested inside another, then the transformation is relative to its parent. Whether the origin of the mesh under construction, or the coordinates of subsequently defined vertices are affected depends on whether the first vertex has yet been defined (see $Vertices and $VerticesUV).
- $Vertices { x1 y1 z1 ... xn yn zn } n >= 0
- An array of vertices for use in future $Triangles, $Quads and $Polygons sections. The first vertex has index 1. The actual world coordinates of the vertex depends on the current transformation matrix defined by the $Transform section. All vertices defined by $Vertices will have the same texture coordinates.
- $VerticesUV { x1 y1 z1 kU1 kV1 ... xn yn zn kUn kVn } n >= 0
- As for $Vertices above, except that each vertex has an associated texture coordinate kU and kV (each in the range [0, 1]).
- $Hints { Anything* }
- Optimisation hints for the display of the containing $Mesh. Any sequence
of tokens is valid. No further information is available about the contents of this section.
The following sections modify the appearance of any subsequently created polygons:
- $Texture { token+ }
- Token represents a valid filename or texture. If token is missing then there is no current texture. Token may be a full pathname but this limits portability of the .ams file. A defined path is searched if the file is a relative pathname. (On the PC version of MathLive, this is given by the Script&TextureLoadPath entry of the mathlive.ini file.)
- $Rgb { k_red k_green k_blue }
- Colour.
- $Surface { k_ambient k_diffuse k_specular k_opacity }
- Surface properties.
- $Quality { PointCloud | WireFrame | Flat | Gouraud | Phong }
- A token not from this list is taken to be Flat. All polygons are single-sided (they are completely transparent from behind). The ordering of the vertices determine which side of the polygon will be rendered. If you want to render both sides of a polygon, it is best to duplicate the vertices for each side so that gouraud (smooth) shading works properly.
- $Triangles { u1 v1 w1 ... u3n v3n w3n }
- n >= 0
- $Quads { t1 u1 v1 w1 ... t4n u4n v4n w4n }
- n >= 0
- $Polygons { { v1 v2 ... vn }* }
- n >=0, n can be different for each polygon in the section.
- Defaults
- Set at the beginning of every $Mesh. Note that these aren't guaranteed,
so it's best to be explicit.
$Quality { Flat }
$Rgb { 0.5 0.5 0.5 }
$Surface { 0.4 0.4 0.4 1 }
$Texture { }
$Transform { 1 0 0 0 0 1 0 0 0 0 1 0 0 0 0 1 }
$Orientation { 1 0 0 0 0 1 0 0 0 0 1 0 0 0 0 1 }
Example
- $Mesh {
- # Define the vertices necessary to display a picture
- $VerticesUV {
- 0 0 0 0 0
- 1 0 0 1 0
- 1 1 0 1 1
- 0 1 0 0 1
- }
- # Define a square displaying a picture
- $Texture { face.bmp }
- $Quads { 1 2 3 4 }
- # Add a red triangle.
- # First we need another vertex
- $Vertices { 1 0 1 }
- # ...and now the triangle
- $Triangles {
- # Turn off the old texture (note the space, without it the opening '{' and
closing '}' would not be recognised by the token scanner.
- $Texture { }
- $Rgb { 1 0 0 } # Red
- 3 4 5 # The single triangle
- }
datasheet