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

Provided by: structure-synth_1.5.0-7_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
         }