The 3-Script(TM) File Format
============================
Mathematica is a registered trademark,
of Wolfram Research, Inc.
PostScript is a registered trademark of Adobe Systems, Inc.
RenderMan is a trademark of Pixar.
Autocad is a registered trademark of Autodesk, Inc.
Mathematica is not associated with Mathematica, Inc.,
Mathematica Policy Research, Inc., or MathTech, Inc.
Copyright 1988-1991 by Wolfram Research, Inc.
All rights reserved. No part of this document may be reproduced,
stored in a retrieval system, or transmitted, in any form or by any
means, electronic, mechanical, photocopying, recording or otherwise,
without the prior written permission of the copyright holder.
Wolfram Research is the holder of the copyright to the Mathematica software
system described in this document, including without limitation such
aspects of the system as its code, structure, sequence, organization,
``look and feel'', programming language and compilation of command
names. Use of the system unless pursuant to the terms of a license
granted by Wolfram Research or as otherwise authorized by law is an infringement of the copyright.
Wolfram Research Inc., makes no representations, express or implied,
with respect to this documentation or the software it describes,
including without limitations, any implied warranties of merchantability
or fitness for a particular purpose, all of which are expressly
disclaimed. Users should be aware that included in the terms and
conditions under which Wolfram Research is willing to license Mathematica is
a provision that Wolfram Research and its distribution licensees, distributors and dealers shall in no
event be liable for any indirect, incidental or consequential
damages, and that liability for direct damages shall be limited to
the amount of the purchase price paid for Mathematica.
In addition to the foregoing, users should recognize that all
complex software systems and their documentation contain errors
and omissions. Wolfram Research shall not be responsible under
any circumstances for providing information on or corrections to
errors and omissions discovered at any time in this document or the
software it describes, whether or not they are aware of the errors
or omissions. Wolfram Research does not recommend the use of the
software described in this document for applications in which errors
or omissions could threaten life, injury or significant loss.
Introduction
============
3-Script is a file format for transferring descriptions of
three-dimensional graphical objects from Mathematica(R) to other programs.
Mathematica internally represents three-dimensional graphical objects
in terms of symbolic graphics primitives such as Polygon and Line.
There are several ways to produce pictures from these graphics
primitives.
Built into Mathematica is the capability to convert the symbolic
description of a collection of graphical objects into a PostScript
representation of a picture. This representation can be rendered on
displays and printers at any resolution. But it gives only one picture
of the graphical objects: information on their original
three-dimensional structure is lost.
Particularly on computers with special-purpose graphics hardware or software, it
is often valuable, however, to sidestep Mathematica's built in PostScript
generation capability, and instead to take a representation of the original
three-dimensional graphical objects, and feed this to special graphics hardware
or software. This may, for example, allow one to generate pictures of objects
being rotated in real time, or may allow much more sophisticated scene
rendering.
The goal of 3-Script is to define a simple format in which information
on three-dimensional graphical objects can be transferred from
Mathematica to external systems.
3-Script specifies a format for plain ASCII files. (In the future, a
byte-encoded version may be developed.) It can be thought of as a
simple language, intended to be simple to generate and to parse.
This document specifies the format for 3-Script files.
The Structure of 3-Script
=========================
There are three kinds of objects in 3-Script: commands, numbers and strings. A
3-Script file consists of a sequence of these objects, separated by white
space.
Each command is followed by ``arguments'', which can be either numbers or
strings. The arguments of one command terminate when the next command is given.
polygon x1 y1 z1 x2 y2 z2 a polygon specified
by any number of vertices
line x1 y1 z1 x2 y2 z2 a line that joins a
sequence of points
point x y z a point
mesh m n z11 z12 ... z21 ... zmn a smooth surface specified by an
m X n array of height values
colormesh m n z11 ... zmn r11 g11 b11 ... b{(m-1)(n-1)}
a smooth surface with colors specified
for center of each patch
color r g b objects that follow have the specified
RGB color Standard 3-Script commands
for three-dimensional objects
The coordinates used in these commands are C format floating point numbers.
They can have any magnitude; only their relative values are significant.
When converting to PostScript, Mathematica can handle polygons that are not
necessarily convex or planar. Most rendering mechanisms for 3-Script are less
general. Notice that even if two polygons share a vertex, the vertex must be
given twice in the 3-Script file. The same is true in symbolic representation
that Mathematica uses. If you need to represent a surface that does not
fold over itself, however, mesh is probably the appropriate command to
use.
The RGB values used in the color and colormesh commands must be
between 0 and 1.
In addition to commands that describe three-dimensional objects, there are also
``directives'' in 3-Script that specify the default viewpoint, lighting and
other parameters to use in displaying the scene. These defaults can be used, for
example, when the renderer is first started, and can later be changed
interactively. Such directives are typically given at the beginning of a
3-Script file.
boundingbox xmin ymin zmin xmax ymax zmax ranges of coordinates of
objects in the scene
viewpoint xr yr zr default relative position
from which to view the scene
ambientlight r g b isotropic ambient light level
lightsources xd1 yd1 zd1 r1 g1 b1 xd2 yd2 zd2 r2 g2 b2
directions and colors of
light sources
3-Script commands used as global directives.
Following the corresponding Mathematica graphics option, the arguments to
viewpoint are coordinates measured from the center of a rectangular box
that encloses all the objects in the scene, scaled so that in these
coordinates the longest side of the box has length 1.
The lighting model provided by basic 3-Script commands is simple
compared to some. It follows the lighting model used by Mathematica for
producing PostScript output. (The inability to produce color gradients
efficiently in standard PostScript makes it superfluous to support more
sophisticated lighting models in that case.) Mathematica assumes that
all surfaces are Lambertian reflectors. In 3-Script, you can introduce
additional commands to cover other cases.
A 3-Script file that represents a tetrahedron.
boundingbox
% Graphics3D objects
-0.942809 -0.834546 -0.333333
0.471405 0.834546 1.
viewpoint
1.3 -2.4 2.
ambientlight
0. 0. 0.
lightsources
1. 0. 1.
1 0 0
1. 1. 1.
0 1 0
0. 1. 1.
0 0 1
polygon
0. 0. 1.
-0.942809 0. -0.333333
0.471405 -0.834546 -0.333333
polygon
0. 0. 1.
0.471405 0.834546 -0.333333
-0.942809 0. -0.333333
polygon
0. 0. 1.
0.471405 -0.834546 -0.333333
0.471405 0.834546 -0.333333
polygon
-0.942809 0. -0.333333
0.471405 0.834546 -0.333333
0.471405 -0.834546 -0.333333
In[1]:= <