GRAPHTAL(1) USER COMMANDS GRAPHTAL(1) NAME graphtal - L-system generation program SYNOPSIS graphtal [options] [file] DESCRIPTION graphtal is a tool for manipulating spT0L-systems (context free, table oriented L-systems with stochastic productions). graphtal reads a file containing an L-system description and starts the interpretation. In addition, graphtal is able to interpret the result graphically, producing different kinds of output. The main reference for the program is the book _T_h_e _V_i_r_t_u_a_l _L_a_b_o_r_a_t_o_r_y: _T_h_e _A_l_g_o_r_i_t_h_m_i_c _B_e_a_u_t_y _o_f _P_l_a_n_t_s by P. Prusink- iewicz and A. Lindenmayer. The language used in graphtal is different from the one in the book and will be described completely in this document. The following sections describe how to run graphtal, the input format accepted and turtle commands implemented. NOTATION o+ [thing] Optional item. o+ Production. o+ Thing Number or String. o+ (thing) Default value(s). o+ thing Keyword. SECTION 1: RUNNING GRAPHTAL OPTIONS Command line options override the settings in the input file. The following options are accepted: -O outfile Sets the output file name. -R xres yres Render at given resolution. The default is set to (400, 400). -E x y z Set eyepoint vector. The default is set to (0 1 0). -L x y z Set lookat vector. The default is set to (0 0 0). Last change: October 27, 1992 1 GRAPHTAL(1) USER COMMANDS GRAPHTAL(1) -U x y z Set up vector. The default is set to (0 0 1). -f angle Set field of view. The default is set to (45) -Dname Define name as 1 (cpp option). -Dname=def Define name as "def" (cpp option). -d drivername Set the output device driver. The default driver is (x11simple). Drivers included: no No turtle interpretation. example Example driver. bbox Calculate bounding box and viewing parameters. rayshade Rayshade driver. x11simple Simple line drawing driver for X11. x11wire Wire frame driver for X11. flat Simple z-buffering. -c Toggle cone spheres generation. If cone spheres are enabled, line segments are connected with spheres. The default is (no cone sphere generation). -s Show the defined hulls. The default is set to (no). -v Verbose output. The default is set to (not verbose). -q Run quietly. The default is set to (don't be quiet). -l Print L-system definition. The default is set to (don't print it). -p Print resulting module string. The default is set to (don't print the modules). -e Erase module after turtle interpretation. The default is set to (don't erase). -h Help: print the command line options. SECTION 2: LANGUAGE DESCRIPTION graphtal accepts a grammar describing spT0L-systems, with the following features: Last change: October 27, 1992 2 GRAPHTAL(1) USER COMMANDS GRAPHTAL(1) o+ D0L-systems (DOL), o+ tables of productions (TOL), o+ productions with parameters (pTOL), o+ stochastically applied productions (spTOL), o+ global and local constants, o+ hull definitions (turtle interpretation with regard to these hulls), o+ production parameters may be strings or real values. All these features may be freely combined. CASE SENSITIVE graphtal is case sensitive. NAMES Two types of names are accepted: _m_o_d_u_l_e names, and _v_a_r_i_a_b_l_e names. Variable names follow the rules for C identifiers: arbitrarily long strings chosen from the character set [A- Za-z_0-9], with digits disallowed as the leading character. Module names are variable names or one of the following spe- cial characters: + - ^ & \ / | $ [ ] { . } ~ %. EXPRESSIONS _E_x_p_r_e_s_s_i_o_n_s generally follow the rules of C expressions. Variable names, string constants and numeric values are operands. The predefined variables and constants: - constants M_PI, M_PI_2, M_PI_4, M_E, M_SQRT2, M_LN2, M_LN10, true, false - variables _t_u_r_t_l_e_x, _t_u_r_t_l_e_y, _t_u_r_t_l_e_z (current position of turtle) and the operators and functions: - logical operators: !, ||, &&, ==, !=, <, <=, >, >= - arithmetic operators: :: (scope operator), +, - (unary and binary), *, /, % (remainder), ** (exponentiation), ^ (exponentiation) - functions _s_i_n, _c_o_s, _t_a_n, _a_s_i_n, _a_c_o_s, _a_t_a_n, _a_b_s, _s_q_r_t, _e_x_p, _l_o_g, _l_o_g_1_0, _r_a_n_d (generate a random number in the range (0,1) ), _g_a_u_s_s (generate a gaussian random number in the range (0,1) ), _i_f (if(a,b,c) <=> if (a) b else c) Last change: October 27, 1992 3 GRAPHTAL(1) USER COMMANDS GRAPHTAL(1) graphtal tries to simplify each expression by evaluating constant subterms. For example the expression sqrt(2*2)*rand() is reduced to 2*rand(). Reals and strings may be combined and string/real, real/string promotion is done at evaluation time according to the following rules: Operators: - _r_e_a_l/_r_e_a_l No promotion necessary. - _r_e_a_l/_s_t_r_i_n_g Convert the second argument to real if possible, other- wise convert the real argument to string -> string/string calculations are applied. - _s_t_r_i_n_g/_r_e_a_l Convert the second argument to string and do string/string calculations. - _s_t_r_i_n_g/_s_t_r_i_n_g Logical operators do string comparison. The arithmetic operator + is defined as string concatenation. For the other arithmetic operators the arguments are converted to real and real/real calculation is done. If this is impossible, an error occurs. Functions: All the function arguments are converted to real. If this is impossible, an error occurs. LSYSTEM graphtal accepts a single file in the format described below from standard input or a given file. The L-system descrip- tion is parsed and the tables of productions are applied to the _a_x_i_o_m as specified within the _a_t_t_r_i_b_u_t_e_s _s_e_c_t_i_o_n. The resulting module string controls a 3d turtle and produces an image. In EBNF an L-system looks like this: LSystem: lsystem Name [ ] [ ] ; GlobalConstants: CONSTANTS An L-system description file may contain any number of con- stants. The scope of a local constant is the table where it Last change: October 27, 1992 4 GRAPHTAL(1) USER COMMANDS GRAPHTAL(1) was defined, whereas the scope of global constant is the whole L-system description. Because local constants may hide the name of a globally defined constant, the scope operator (::) may used to have explicitly access to global scope. Example: lsystem test; /* definition of global constants */ const a = 5*sin(M_PI); b = a*a; table one { /* local constant definition within a table, */ /* access to global constant via scope operator */ const a = ::a; ... }; ConstantsDef: const Constants: | Constant: Name = ; HULLS Hulls are a special feature of graphtal, which allows a glo- bal control of growth in the interpretation process. A hull consists of primitives . Any number of hulls may be defined. If a hull is activated, the turtle moves with regard to that hull, i.e. when the current path of the turtle intersects a hull primitives, the interpretation is stopped and one of two possible procedures is executed: o+ reflect the turtle on the surface we hit (regarding a reflectance factor) o+ cut the current branch The definition of primitives has been adapted from Craig Kolbs rayshade. This allows a user to include already defined objects into the L-system description file. As an example the definition of a house could affect the growth of a tree in the way, that the tree may not penetrate the house. Example: hull aHull { plane 0 0 0 0 0 1 Last change: October 27, 1992 5 GRAPHTAL(1) USER COMMANDS GRAPHTAL(1) cylinder 1 0 0 0 /* unit cylinder */ 0 0 1 scale 1 1 2 translate 0 0 5 }; Hulls: | Hull: hull Name { } ; Primitives: [] | [] Primitive: sphere Radius Xpos Ypos Zpos | triangle Xv1 Yv1 Zv1 Xv1 Yv1 Zv1 Xv1 Yv1 Zv1 | plane Xpos Ypos Zpos Xnorm Ynorm Znorm | cylinder Radius Xbase Ybase Zbase Xapex Yapex Zapex | cone Rbase Xbase Ybase Zbase Rapex Xapex Yapex Zapex Transforms: Transform: translate Xtrans Ytrans Ztrans scale Xscale Yscale Zscale rotate Xaxis Yaxis Zaxis Degrees transform A B C D E F G H I [Xt Yt Zt] Arguments for the primitives and transformations are numeric values and constants. TABLES A table is a collection of productions. Any number of tables may be defined within a description file. Designing an L- system in a table oriented manner, allows the user to modu- larize the productions. For instance the L-system of a tree could consist of two tables, one for the branches and another for the leafs. Please look at the examples for further details. Last change: October 27, 1992 6 GRAPHTAL(1) USER COMMANDS GRAPHTAL(1) Tables: |
Table: table Name { } ; PRODUCTIONS graphtal allows the definition of productions with parameter and probabilities. All the productions are context free. It's better to show some examples instead of giving long explanations: A production in a D0L-System: MatchingModule -> any any any; A production with parameters and condition: F(l) : l > 0.5 -> F(l2) A(l+1); An "empty" production (eat the module): Leaf(season) : season == "winter" -> ; A stochastic production: Branch(l) -> (0.2) F(l) -> (0.5) F(l/2) F(l/2) -> (0.3) ; And now the detailed EBNF for : Productions: | Production: [ ] ; Predecessor: Name [ ] Arguments: ( ) Parameters: Name | , Name Condition: : Last change: October 27, 1992 7 GRAPHTAL(1) USER COMMANDS GRAPHTAL(1) Successors: | Successor: -> [ ] [ ] Modules: | Module: Name [ ( ) ] Probability: Number ExpressionList: | , ATTRIBUTES In the attributes section of the L-system description file, all the parameters are set, which affect the interpretation process. The _a_x_i_o_m and _d_e_r_i_v_a_t_i_o_n attributes have to be declared. Here's the list of attributes: Attributes: attributes { } ; AttributesList: derivation ; | axiom ; | roll ; | turn ; | pitch ; | angle ; | forward ; | randomize [ ] ; | tropism , , ; | weight ; | eye , , ; | lookat , , ; | up , , ; | fov ; | coneres Number ; | sphereres Number ; Derivations: Name [ ] | , Name [ ] Last change: October 27, 1992 8 GRAPHTAL(1) USER COMMANDS GRAPHTAL(1) Steps: ( ) | ( infinity ) DERIVATION The derivation attributes specifies the tables to be applied to the axiom. Global constants may be used in step defini- tions. Examples: Apply table1 once and table2 10 times to the axiom: derivation table1, table2(10); Apply table1 once to the axiom and table2 as long a produc- tion of the table matches any module in the module string. derivation table1(1), table2(infinity); AXIOM Set the axiom of the L-system. Global constants may be used in expressions. ROLL, TURN, PITCH, ANGLE, FORWARD Set the default values for turtle commands without parame- ters. _p_i_t_c_h, _r_o_l_l and _t_u_r_n specifies the default rotation angle for one of the three rotation operations. The command _a_n_g_l_e sets pitch and turn, roll to the same rotation angle. The _f_o_r_w_a_r_d command specifies the default step for turtle movements. RANDOMIZE Initialize the random number generator. randomize; calls srand with the current time. randomize number; calls srand with number. TROPISM, WEIGHT Set analytic tropism function (see also TROPISM in section 3). The tropism vector and the weight function may depend on the turtle position in the interpretation process by using the predefined variables _t_x, _t_y and _t_z. This can't be done within the production rules, because the parameters of the modules are determinated before the interpretation pro- cess starts. EYE, LOOKAT, UP, FOV Set viewing parameters. graphtal uses a simple model, simi- lar to Craig Kolbs rayshade. CONERES, SPHERERES Set resolution for cone and sphere tesselation. The values Last change: October 27, 1992 9 GRAPHTAL(1) USER COMMANDS GRAPHTAL(1) set are used by the flat and wire frame device driver. OTHER FEATURES COMMENTS C-style (delimited by /* and */) and C++-style comments (delimited by //) are accepted at any point in the input. CPP cpp (C language preprocessor) is invoked as the first pass of any L-system interpretation. Therefore you may add includes, defines and macro definitions to the input file. The command line option -D (see OPTIONS) attaches a value to a name which may be used as an additional parameter in the i-system description. This is useful for animations. See the examples for further details. SECTION 3: TURTLE COMMANDS A lot of module names have their special meaning the interpretation process. Here's the list of module bindings in graphtal: BASIC MANIPULATIONS F Move turtle forward drawing a line (cylinder) from start to end point. _F(_3) moves turtle forward 3 steps. _F move a default step, which is initially set to 10 but may be redefined in the attributes section with the command _f_o_r_w_a_r_d (see ATTRIBUTES). f, G Move turtle forward without drawing a line. For examples see _F. pt, ^ Rotate turtle around its left axis in positive direction, i.e. counter clock wise (pitch). _p_t(_4_5) or ^(_4_5) pitches the turtle 45 degrees around it's left axis. _p_t pitches the turtle around it's left axis by the default rotation angle, which is initially set to 45 degrees, but may be changed in the attributes section with the commands _p_i_t_c_h or _a_n_g_l_e. & Pitch turtle in negative direction (clock wise). ro, / Rotate turtle around it's heading in positive direction (roll). Default is 45 degrees, but may be changed in the attributes section with the com- mands _r_o_l_l or _a_n_g_l_e. See pitch for examples. \ Roll the turtle in negative direction. For exam- ples see pitch. Last change: October 27, 1992 10 GRAPHTAL(1) USER COMMANDS GRAPHTAL(1) tu, - Rotate turtle around it's up direction in positive direction (turn). Default is 45 degrees, but may be changed in the attributes section with the com- mands _t_u_r_n or _a_n_g_l_e. See pitch for examples. + Turn the turtle in negative direction. See pitch for examples. rv, $ Rotate turtle vertically, i.e. align the turtle's heading to a vertical position. | Reverse the turtle -> tu(180). [ Push current turtle state on the turtle stack (start branch). ] Set turtle state to the value on top of turtle stack (end branch). wi Set line width to new value. Default width is 1. The line width command specifies the radius(!) of the cylinder which a _F would draw. wi(10) -> new line width is 10 (= radius of the cylinder to be drawn, therefore the width of the cylinder is 20). % Cut a branch. If an % symbol is detected by the turtle interpreter all the following modules are ignored until a ] (end branch) symbol. Subbranches are deleted as well. G % F F [ F ] ] pt F is interpreted as G pt F. GEOMETRIC PRIMITIVES { Start polygon. Polygon definitions may be nested. { . F . tu(45) F . } generates a triangle. sv, . Save current turtle position as polygon vertex. } End of polygon definition. poly Draw a polygon with given vertices. poly(0,0,0, 0,10,0, 10,10,0, 10,0,0) generates a polygon with 4 vertices. tri Draw a triangle with given vertices. The first 9 parameters are regarded as the triangle vertices, the rest is ignored. Last change: October 27, 1992 11 GRAPHTAL(1) USER COMMANDS GRAPHTAL(1) s Draw a sphere at current location with given radius (default is 1). s(25) draw a sphere with radius 25 at turtle posi- tion. MACROS AND LIBARY OBJECTS graphtal supports the definition of macros (subobject) and library object (predefined objects). These features depend on the device driver used. Macros are supported by the _w_i_r_e _f_r_a_m_e and the _r_a_y_s_h_a_d_e device drivers. Library objects are known to the _r_a_y_s_h_a_d_e driver. The other device drivers do not support these features and ignore the corresponding modules. sm Start a macro definition. Macros may not be nested. While defining a macro, all the geometric primitives generated are collected by the device driver. This process comes to an end when the end macro (em) command occurs in the module string. sm("leaf") F em Generate a macro with the name "leaf" containing a single cylinder object. em End of macro definition. See start macro. xm Execute a macro. A already defined macro can be execute at any point of the interpretation pro- cess. The geometric primitives of the choosen macro are transformed according to the turtle position and the scale factor given by the execute macro command. xm("leaf") Include the primitives of the macro "leaf" at the turtle location. xm("leaf", 0.5) Scale the primitives of the macro "leaf" and include them at the turtle location. lib Include a predefined library object at the current turtle location. An additional scaling factor may be specified. lib("apple") Generate the library object "apple" at the current turtle location. lib("apple", 1.2) Generate the library object "apple" at the current turtle location and scale Last change: October 27, 1992 12 GRAPHTAL(1) USER COMMANDS GRAPHTAL(1) it by 1.2. RENDERING ATTRIBUTES texture Set texture attributes for the following primi- tives. This feature is implemented for the _r_a_y_s_h_a_d_e _d_r_i_v_e_r, all the others ignore it. The implementation is very simple: the user may give a string describing the texture to be applied. It's the device driver's task to react in an appropri- ate manner. texture("texture bump 0.3") The rayshade driver adds to each following primi- tives the string "texture bump 0.3". co Set the drawing color. All the known colors are stored in the file "colors.def" each line in the format "R G B colorName". Any number of colors may be added to this file. The defined colors are taken from the X11 distribution. co("ivory") change the color to "ivory". TROPISM With tropism vectors it's possible to manipulate the growth of the L-system towards a defined direction. For example a plant growing towards the position of the sun. If the tro- pism vector is the zero vector or the tropism weight equals zero, then tropism calculations are disabled. t Set tropism vector (see also attributes TROPISM). Initially tropism computations is disabled and the tropism vector is set to (0,0,-1). t(1,0,0) set tropism vector to (1,0,0). t(1,0,0,0.5) set tropism vector to (1,0,0) and weight factor to 0.5 -> enable tropism computa- tion. we Set weight factor for tropism computation. Ini- tially the weight factor is set to 0.5. A factor of 0 disables tropism calculation. HULLS As explained in section 2, the turtle can react in two dif- ferent ways to a hit with a hull. The reflect behaviour is specified through the _a_h command, and the cut behaviour through cb. ah Activate a hull defined in the L-system descrip- tion and set the reflectance factor. Last change: October 27, 1992 13 GRAPHTAL(1) USER COMMANDS GRAPHTAL(1) ah(nameOfTheHull, reflectanceFactor) Activate the hull with the name "nameOfTheHull". If the turtle hits a hull primitive, reflect according to reflectanceFactor (0=no reflectance, 1=full reflectance). ah("house") activate the hull "house", reflectance factor is 1 as default. ah("house", 0.3) activate the hull "house", reflectance factor is 0.3 dh Deactivate the hull set (if any). cb Enable/disable cutting of branches when a hull primitive is hit. cb or cb(1) cut the branch when hull is hit. cb(0) don't cut (default). SECTION 4: DEVICE DRIVERS EXAMPLE DEVICE The example driver produces a ASCII dump of the primitives generated. It shows the easiest way to implement a driver. BBOX DEVICE The bbox driver computes the bounding box and gives a hint for the viewing parameters of the objects defined by the L- system description. This is useful for the _f_l_a_t _d_e_v_i_c_e, which does no automatic view computations. LINE DEVICE (X11) This driver generates a simple line drawing of the object defined by the L-system. Line width, color, textures, spheres, macros and library object are not supported by this driver. Viewing parameters are automatically set, when none are provided by the user. WIRE DEVICE (X11) The wire device driver draws a more realistic image of the object than line device. Not supported are colors, textures and library objects. Viewing parameters are also set automatically, when none are provided. FLAT DEVICE The flat device works with a z-buffer algorithm, which is able to shade convex and concave polygons. Shading calcula- tions are done with regard to the light source located at the eyepoint. The driver does not depend on the number of polygons, therefore even very large scenes can be visual- ized. As a drawback of this feature, the viewing parameters Last change: October 27, 1992 14 GRAPHTAL(1) USER COMMANDS GRAPHTAL(1) have to be provided by the user (use BBOX DEVICE to calcu- late them). Textures and library objects are not supported by this driver. The output of the rendering process is an image in _p_p_m _f_o_r_m_a_t (portable pixmap). There are two ways to capture the image: graphtal -d flat ... -O tree.ppm tree.lsys graphtal -d flat ... tree.lsys > tree.ppm RAYSHADE DEVICE The rayshade device is the most complete of all the drivers. It generates output for the raytracer _r_a_y_s_h_a_d_e. The driver produces at least two output files: graphtal -d rayshade anExample.lsys generates the files default.ray and default.ray.def graphtal -d rayshade -O anExample.ray generates the files anExample.ray and anExample.ray.def. The file name.ray contains the options for the rendering process and in the name.ray.def file the geometric primi- tives are stored. For each macro definition, the rayshade driver produces it's own file with the name macrName.ray.def. If library objects are used, a file with the name libraryName.ray.lib must be provided by the user for each object. ENVIRONMENT With the environment variable COLORFILE the path and the name for the color file can be specified. With setenv COLORFILE ~/includes/colors.def graphtal will read the color definition file specified, instead of the default (= colors.def in the working direc- tory). AUTHOR Christoph Streit (streit@iam.unibe.ch) COPYRIGHT NOTICE Copyright (C) 1992 Christoph Streit All rights reserved. This software may be freely copied, modified, and redistri- buted provided that this copyright notice is preserved on Last change: October 27, 1992 15 GRAPHTAL(1) USER COMMANDS GRAPHTAL(1) all copies. You may not distribute this software, in whole or in part, as part of any commercial product without the express con- sent of the authors. There is no warranty or other guarantee of fitness of this software for any purpose. It is provided solely "as is". OTHER COMMENTS Please send bugs (accompanied by L-systems causing them), interesting L-systems for inclusion in the release, enhance- ments, and suggestions to the author via email. Last change: October 27, 1992 16