Provided by: structure-synth_1.5.0-7_amd64 bug

NAME

       structure-synth - application for creating 3D structures

SYNOPSIS

       structure-synth

DESCRIPTION

       Structure  Synth is an application for creating 3D structures from a set of user specified
       rules. The resulting structures can be viewed in the integrated OpenGL viewer or  exported
       to  various  formats.  The program was inspired by the CFDG syntax by Chris Coyne, and the
       Context Free GUI by Mark Lentczner and John Horigan.

STATES, TRANSFORMATIONS AND ACTIONS

       Structure Synth is all about states. A state describes the current coordinate  system  and
       the  current coloring mode. The coordinate system determines the position, orientation and
       size of all object drawn while in the current state.

       States are modified by transformations. For instance we can move the coordinate system one
       unit  in  the x-direction by applying the transformation: { x 1 }. Similarly we can rotate
       the coordinate system 90 degrees about the x-axis  by  applying:{  rx  90  }.  States  are
       automatically combined while parsing, that is { x 1 x 1 } is equal to { x 2 }.

       States  can  be combined with rule calls to create actions. { x 2 } box is an example of a
       transformation followed by a rule call. 'box' is a built-in rule. Not  surprisingly,  this
       rule draws a box located at (0,0,0) -> (1,1,1) in the current coordinate system.

   Iterated actions:
       It  is  possible  to apply iterated actions, this is done using the multiplication symbol:
       for instance 3 * { x 2 } box would be equal to creating three actions:

         { x 2 } box
         { x 4 } box
         { x 6 } box

   Color transformations:
       Similar to the spatial transformations it  is  also  possible  to  transform  the  current
       rendering  color.  Structure  Synth  uses HSV (Hue, Saturation and Value) for representing
       colors - this is perhaps not as familiar as the RGB color model,  but  offers  a  slightly
       more  intuitive  representation once you get used to it (at least that is what some people
       claim - personally I still  find  it  easier  think  in  terms  of  red,  green  and  blue
       components).  The  color  transformations  are  applied  using the 'hue', 'saturation' and
       'value' operators.

       The next example demonstrates both iterated actions and color transformations  to  draw  a
       nice color cube:

         10 * { x 1 hue 36 } 10 * { y 1 sat 0.9 } 10 * { z 1 b 0.9 } box

       Here is another example demonstrating different kinds of transformations:

         10 * { x 2 } box
         1 * { y 2 } 10 * { x 2 rx 6 } box
         1 * { y 4 } 10 * { x 2 hue 9 } box
         1 * { y 6 } 10 * { x 2 s 0.9 } box

   Built-in rules:
       The  Box  is  an  example of one the primitives - built-in rules - in Structure Synth. The
       other built-in rules are: Sphere, Dot, Grid, Line, Cylinder, Mesh, CylinderMesh.

MAKING RULES

       Custom rules are the key to creating  complex  and  sophisticated  structures.  Rules  are
       created  using the 'rule' keyword. A rule can used the same way as any built-in primitive.
       The most important aspect of rules are, that they are able to call themselves. Take a look
       at the following example:

         R1

         rule R1 {
           { x 0.9 rz 6 ry 6 s 0.99  sat 0.99  } R1
           { s 2 } sphere
         }

       Notice  that  this  rule  recursively  calls  itself.  It  would never terminate - however
       Structure Synth has a default maximum recursion depth of 1000 recursions. This  value  can
       be changes using the 'set maxdepth xxx' command. Another way to force termination would be
       using the 'set maxobjects xxx' keyword, which makes Structure  Synth  keep  track  of  the
       number of objects drawn.

   Adding some randomness:
       Now, in order to things interesting, we will probably want to create something less static
       - by adding some randomness. In Structure Synth this  is  achieved  by  creating  multiple
       definitions for the same rule:

         R1

         rule R1 {
           { x 0.9 rz 6 ry 6 s 0.99  sat 0.99  } R1
           { s 2 } sphere
         }

         rule R1  {
           { x 0.9 rz -6 ry 6 s 0.99  sat 0.99  } R1
           { s 2 } sphere
         }

       Notice  the 'R1' rule has two definitions. Now, whenever the Structure Synth builder needs
       to call the 'R1' rule, it will choose one of the definitions at random.

REFERENCE

   Actions:
       Termination criteria:

       set maxdepth [integer]:
              Breaks after [integer] iterations (generations). This will also serve  as  a  upper
              recursion limit for all rules.

       set maxobjects [integer]:
              After [integer] objects have been created, the construction is terminated.

       Other:

       set seed [integer]:
              Allows you to set the random seed. This makes it possible to reproduce creations.

       set background [color]:
              Allows you to set the background color. Colors are specified as text-strings parsed
              using Qt's color parsing, allowing for standard HTML RGB specifications (e.g.  #F00
              or #FF0000), but also SVG keyword names (e.g. red or even lightgoldenrodyellow).

   Rule modifiers:
       md / maxdepth [integer]:
              Rule Retirement.Sets the maximum recursive for the rule. The rule would not execute
              any actions after this limit has been reached.

       md / maxdepth [integer] > [rulename]:
              Rule Retirement with substitution.Sets the maximum recursive for  the  rule.  After
              this limit has been reached [rulename] will be executed instead this rule.

       w / weight [float]:
              Ambiguous  rules.If  several  rules  are  defined  with  the  same  name,  a random
              definition is chosen according to the  weight  specified  here.  If  no  weight  is
              specified, the default weight of 1 is used.

   Transformations:
       Geometrical transformations:

       x [float]:
              X axis translation. The float argument is the offset measured in units of the local
              coordinate system.

       y [float]:
              Y axis translation. As above.

       z [float]:
              Z axis translation. As above.

       rx [float]:
              Rotation about the x axis. The 'float' argument is the angle specified in  degrees.
              The rotation axis is centered at the unit cube in the local coordinate system: that
              is the rotation axis contains the line segment from (0, 0.5, 0.5) -> (1, 0.5, 0.5).

       ry [float]:
              Rotation about the y axis. As above.

       rz [float]:
              Rotation about the z axis. As above.

       s [float]:
              Resizes the local coordinate system. Notice that  the  center  for  the  resize  is
              located at the center of the unit cube in the local system (at (0.5,0.5,0.5)).

       s [f1] [f2] [f3]:
              Resizes  the  local  coordinate  system.  As above but with separate scale for each
              dimension.

       m [f1] ... [f9]:
              Applies the specified 3x3 rotation matrix to  the  transformation  matrix  for  the
              current  state.  About  the argument order: [f1],[f2],[f3] defines the first row of
              the matrix.

       fx:    Mirrors the local coordinate system about the x-axis. As above the mirroring planes
              is centered at the cube.

       fy:    Mirrors the local coordinate system about the y-axis.

       fz:    Mirrors the local coordinate system about the z-axis.

       Color space transformations:

       h / hue [float]:
              Adds  the  'float' value to the hue color parameter for the current state. Hues are
              measured from 0 to 360 and wraps cyclicly - i.e. a hue of 400 is equal to a hue  of
              40.

       sat [float]:
              Multiplies  the  'float'  value with the saturation color parameter for the current
              state. Saturation is measured from 0 to 1 and is clamped  to  this  interval  (i.e.
              values larger then 1 are set to 1).

       b / brightness [float]:
              Multiples  the  'float'  value  with the brightness color parameter for the current
              state. Brightness is measured from 0 to 1 and is clamped to this  interval.  Notice
              that  parameter  is  sometimes  called 'V' or 'Value' (and the color space is often
              refered to as HSV).

       a / alpha [float]:
              Multiplies the 'float' value with the alpha color parameter for the current  state.
              Alpha  is  measured  from 0 to 1 and is clamped to this interval. An alpha value of
              zero is completely transparant, and an alpha value of one is completely opaque.

       color [color]:
              This commands sets the color to an absolut color (most  other  transformations  are
              relative  modifications on the current state). Colors are specified as text-strings
              parsed using Qt's color parsing, allowing  for  standard  HTML  RGB  specifications
              (e.g.   #F00   or   #FF0000),  but  also  SVG  keyword  names  (e.g.  red  or  even
              lightgoldenrodyellow).

       Drawing primitives:

       box:   solid box

       grid:  wireframe box

       sphere:
              the round thingy (as of now this primitive has some issues -  e.g.  ellipsoids  are
              not working.)

       line:  along x axis, centered in y,z plane.

       point: centered in coordinate system.

       triangle:
              creates    a    custom    polygon.    Specify    the    coordinates   as   follows:
              Triangle[0,0,0;1,0,0;0.5,0.5,0.5]

       mesh:  prototype mesh

       cylinder:
              the symmetry axis will be the current x axis. [Not implemented]

       tube:  polygonal cylinder (will be drawn smoothly as the  coordinate  system  transforms).
              [Not implemented]

   Preprocessor commands:
       #define varname value:
              substitutes every occurrence of 'varname' with 'value'. Value may contain spaces.

   For Context Free / CFDG users:
       The EisenScript syntax in Structure Synth has a lot in common with CFDG.

       There are however a few important differences:

       Context sensitivity:
              A  CFDG  script  can  be  viewed  as  a  grammar,  where  the  production rules are
              independent of their context - or put differently -  when  choosing  between  rules
              CFDG  does  not  have  any  knowledge of the history of system. This 'Context Free'
              property of CFDG was deliberately omitted  in  EisenScript,  simply  for  pragmatic
              reasons:  some  structures  would be difficult to create without having some way to
              change the rules after a certain number of recursions.

       The 'startrule' statement:
              in CFDG startrules  are  explicitly  specified.  In  EisenScript,  a  more  generic
              approach  is  used:  statements which can be used in a rule definition, can also be
              used at the top-level scope, so in order to specify a start-rule,  just  write  the
              name of the rule.

       Termination criteria:
              in  CFDG recursion automatically terminates when the objects produced are too small
              to be visible. This is a very elegant solution, but it is  not  easy  to  do  in  a
              dynamic 3D world, where the user can move and zoom with the camera. Several options
              exist in Structure Synth for terminating the rendering.

       Transformation order:
              in CFDG transformations (which CFDG refers to as adjustments) in curly brackets are
              not applied in the order of appearence, and if multiple transformations of the same
              type are applied, only the last one is actually carried out. For transformations in
              square  brackets  in  CFDG the order on the other hand is significant. In Structure
              Synth the transformation order is always significant: transformations  are  applied
              starting from the right-most one.

EXAMPLE

       Below is an EisenScript sample:

         /*
           Sample Torus.
         */

         set maxdepth 100
         r1
         36  * { x -2 ry 10   } r1

         rule r1 maxdepth 10 {
            2 * { y -1 } 3 * { rz 15 x 1 b 0.9 h -20  } r2
            { y 1 h 12 a 0.9  rx 36 }  r1
         }

         rule r2 {
            { s 0.9 0.1 1.1 hue 10 } box // a comment
         }

         rule r2 w 2 {
            { hue 113 sat 19 a 23 s 0.1 0.9 1.1 } box
         }

SEE ALSO

       http://structuresynth.sourceforge.net/

                                            April 2009                         Structure Synth(1)