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]:= <