Ubuntu Manpage: structure-synth - application for creating 3D structures

Provided by: structure-synth_1.5.0-6build1_amd64

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:

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:

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
         }