TYPE: SOP
TITLE: LSystem SOP

The LSystem operation creates organic objects such as trees, plants, flowers 
which can grow over time.

Production Rule Syntax:

~c(
[lc<]pred[>rc][:cond]=succ[:prob]

lc       - Optional left context symbol
rc       - Optional right context symbol
pred     - Predecessor symbol to be replaced
cond     - Conditional expression
succ     - Replacement string
prob     - Probability of rule execution expression

e.g.  A< F(i) >B :i<10 = F(5)F(i+1) :0.5
~c)

The rule strings use a number of built in characters to describe how
to build the geometry given a string.  These characters often can take
optional parameters.  For example, "F" could be F(3,2).  The
parameters use their own expression language different than normal
Houdini expressions.  Valid functions and predefined variables are
listed under Local Variables.

The Rule, Context Ignore, and Premise strings do not go through the
standard Houdini string parser, as they can contain reserved
characters such as \ or $.  One can, however, escape into the standard
parser with ` (backquote).  For example:

~c(
A = !"`strdup($F, "/(360/$F)[B]")`
~c)

To place ` or \ inside the escaped string, a preceeding \ is required.

Examples:
    F(l,w,s,d) - Move forward (creating geometry) distance l of width
	         w using s cross sections of d divisions each.
    H(l,w,s,d) - Move forward half the length (creating geometry)
		 distance l of width w using s cross sections of d
		 divisions each.
    G(l,w,s,d) - Move forward but don't record a vertex distance l of
	         width w using s cross sections of d divisions each.
    f(l,w,s,d) - Move forward (no geometry created) distance l of
	         width w using s cross sections of d divisions each.
    h(l,w,s,d) - Move forward a half length (no geometry created)
		 distance l of width w using s cross sections of d
		 divisions each.
    J(s,x,a,b,c) K(s,x,a,b,c) M(s,x,a,b,c) - Copy geometry from leaf input 
	       J, K or M at the turtle's position after rescaling and
	       reorienting the geometry.  The geometry is scaled by
	       the s parameter (default Step Size) and stamped with
	       the values a throuh c (default no stamping).  Stamping
	       occurs if the given parameter is present and the
	       relevant Leaf Param is set.  The x parameter is not
	       used and should be set to 0.
    T(g)     - Apply tropism vector (gravity).  This angles the turtle
	       towards the -y axis.  The amount of change is governed by g.  The
	       default change is to use the Gravity parameter.
    +(a)     - Turn right a degrees.  Default Angle.
    -(a)     - Turn left a degrees (minus sign).  Default Angle.
    &(a)     - Pitch up a degrees.  Default Angle.
    ^(a)     - Pitch down a degrees.  Default Angle.
    \(a)     - Roll clockwise a degrees.  Default Angle.
    /(a)     - Roll counter-clockwise a degrees.  Default Angle.
    |        - Turn 180 degrees
    *        - Roll 180 degrees
    ~~(a)       - Pitch / Roll / Turn random amount up to a degrees.
	       Default 180.
    ~h(&quot;~h)(s)     - Multiply current length by s. Default Step Size Scale.
    !(s)     - Multiply current thickness by s.  Default Thickness Scale.
    ;(s)     - Multiply current angle by s.  Default Angle Scale.
    _(s)     - Divide current length (underscore) by s.  Default Step
               Size Scale.
    ?(s)     - Divides current width by s. Default Thickness Scale.
    @(s)     - Divide current angle by s.  Default Angle Scale.
    '(u)     - Increment color index U by u.  Default UV Increment's
	       first parameter.
    #(v)     - Increment color index V by v.  Default UV Increment's
               second parameter.
    %        - Cut off remainder of branch
    $(x,y,z) - Rotates the turtle so the upvector is (0,1,0).  Points
	       the turtle in the direction of the point (x,y,z).  Default
	       behaviour is only to orient and not to change the direction.
    [        - Push turtle state (start a branch)
    ]        - Pop turtle state (end a branch)
    {        - Start a polygon
    .        - Make a polygon vertex
    }        - End a polygon
    g(i)   - Create a new primitive group to which subsequent geometry 
	       is added.  The group name is the Group Prefix followed
	       by the number i.  The default if no parameter is given
	       is to create a group with the current group number and
	       then increment the current group number.
    a(attrib, v1, v2, v3) - This creates a point attribute of the name
	       attrib.  It is then set to the value v1, v2, v3 for the
	       remainder of the points on this branch, or until
	       another a command resets it.  The v2 & v3 are optional,
	       if not present, an attribute of fewer floats will be
	       created.  The created attribute is always of float type
	       and with zero defaults.   For example, the rule a("Cd",
	       1, 0, 1) added to the start of the premise will make the
	       lsystem a nice pugnacious purple.

Inputs:
    Leaf J,K & M    - This geometry is used by the J, K & M rules
    Meta Test Input - This geometry is used by the in() function to
                      determine bounding regions (for topiaries)

Local Variables:
    acos(v)	- Arc cosine, the inverse of cosine.  It will return a
		  result in degrees.
    asin(v)	- Arc sine, the inverse of sine.  It will return a
	    	  result in degrees.
    cos(angle)	- Cosine.  The angle should be given in degrees. 
    sin(angle)	- Sine.  The angle should be given in degrees. 
    chan(idx)   - Returns the value the lsystem channel evaluated at
		  the current time.  The name of the channel comes
		  from the LSystem Channel Prefix appended by the
		  number which idx evaluates to.  Eg: A LSystem
		  Channel Prefix of "spare" will cause chan(3) to
		  evaluate the channel "spare3" at the current time.
    min(a, b)	- Returns the lower of a and b.
    max(a, b)	- Returns the higher of a and b.
    in(x, y, z) - This determines if the point (x, y, z) is inside the
		  Meta Test Input.
    pic(x, y, plane) - This evaluates the LSystem Picture at
	    	  coordinates (x, y).  These should be in the range
		  0..1.  The plane is an integer corresponding to
		  which channel to evaluate.  0 will calculate the
		  luminance, 1 red, 2 green, and 3 blue.  The result
		  is a value from 0..1.
    rand(seed)  - This finds a random number between 0 and 1 using the
		  given seed.  See "exhelp rand" for details.  A quick
		  random number can be computed with rand(i).
    a		- The LSystem angle parameter.
    b		- The LSystem b parameter.
    c		- The LSystem c parameter.
    d		- The LSystem d parameter.
    g		- Initially 0.  After that it is set to the age of the
		  current rule.
    i		- The offset into the current lsystem string where the
		  rule is being applied.
    t		- Initially 0.  After that it is set to the iteration
		  count.
    x, y, z	- The current turtle position in space.
    A		- The arclength from the root of the tree to the
		  current point.
    L		- The current length increment at the point.
    T		- The LSystem gravity parameter.
    U		- The colour map U value.
    V		- The colour map V value.
    W		- The current width at the current point.

Parameters:
Geometry
    Type	- Skeleton will create wires along the turtle's path.
		  Tube will construct tubes.  A tubed path can also be
		  created by generating a skeleton lsystem and
		  appending a Polywire SOP.
    Generations - The number of times to repeat the rule-substitution.
		  If a fractional number is specified and a continuous
		  option is set, the last rule substituted will have
		  its effect scaled.  This allows for realistic
		  inter-generational growth.
    Random Scale - If non-zero, all the lengths specified by F and
		  other similar turtle functions will be scaled
		  randomly.
    Random Seed - The seed to use for the random number generator.  By
		  varying this on a lsystem using random rules (Ie:
		  random scale, ~~, or probabilistic rules) one can
		  generate different instances of the lsystem.
    Continuous Angles - If set, the angles rotated by the last
		  generation's turtle operations will be scaled by the
		  amount into the generation.			    
    Continuous Length - If set, the lengths taken by the last
		  generation's turtle operations will be scaled by the
		  amount into the generation.			    
    Continuous Width - If set, the widths generated by the last
		  generation's turtle operations will be scaled by the
		  amount into the generation.			    
    Apply Color - If set, the LSystem will output a colour attribute
		  on each point.  The colour value will be found by
		  looking up into the Image File at the current U & V
		  positions.  The current U & V is alterred with the '
		  and # turtle operations.
    Image File   - This is the image file which is used for the Apply
		  Color operation.  The image files used by the pic()
		  expression is under Funcs tab.
    UV Increment - These determine the default U and V increments of
		  the ' and # turtle operations.
    Point Attributes - If the type is Skeleton, this is available.
		  Turning this on will cause the creation of many
		  point attributes to be created to track how each
		  point was generated:
	width   - The width of the tube that would have been generated.
	segs	- The number of segments that would be made on a tube.
	div	- The number of divisions the tube would be divided into.
	lage    - The vertical increment from the root of the tree.
		  This is affected by the Tube::Vertical Increment
		  parameter.  It is similar to arc, but not dependent
		  on edge length.
	arc	- The arc length from the root of the turtles path to
	    	  this point.
	up	- The up vector of the turtle at this point.
	gen	- The generation that created this point.
Tube
    Rows	- The number of rows to divide tubes into.  A value of
		  3 will cause the tubes to be swept triangles.
    Cols	- The number of columns to divide the tubes in.  A
		  value of 4 means one F will create 4 cross sections.
    Tension	- How straight the tubes should sweep to their
		  destination point.
    Branch Blend - How much a new branch should inherit off an old
		  branches direction.
    Thickness   - Default width of the tubes.
    Thickness Scale - How much the ! operation will affect the
		  thickness.
    Apply Tube Texture Coordinates - If checked, the tubes will
		  generate uv texture coordinates.
    Vertical Increment - The amount each tube will increment the V
		  texture coordinate.
Values
    Step Size	- The default movement of a movemnt, such as F, command.
    Step Size Scale - The number used by the " command.
    Angle       - The default angle for an angle, such as /, command.
		  This also becomes the variable a in the expression.
    Angle Scale - The number used by the ; command.
    Variable b  - The value of the expression variable b.
    Variable c  - The value of the expression variable c.
    Variable d  - The value of the expression variable d.
    Gravity	- The amount of tropism from the T command.  Also
		  becomes the value of the expression variable T.
    Number Of Variables - This multiparm allows the assignment of an
		  arbitrary number of new expression variables.
    Variable Name - The name of the expression variable.  This is a
		  single character.  Check the Local Variables section
		  to see what variables are already reserved.
    Variable Value - The value of the expression variable.
Funcs
    Pic Image File - The image file to use with the pic() expression
		  function.
    Group Prefix - The prefix used by g command.
    Channel Prefix - The prefix used by the chan() expression function.
    Leaf Param A - This is the name of the stamp parameter to stamp
		  the leaf with.  The value of the stamp comes from
		  the J, K, or M operation.  It can be read upstream
		  using the param() function.
    Leaf Param B - This is the name of the stamp parameter to stamp
		  the leaf with.  The value of the stamp comes from
		  the J, K, or M operation.  It can be read upstream
		  using the param() function.
    Leaf Param C - This is the name of the stamp parameter to stamp
		  the leaf with.  The value of the stamp comes from
		  the J, K, or M operation.  It can be read upstream
		  using the param() function.

Rules
    Read Rules From File - If this is set, the rule fields are
		  ignored.  Instead, the Rule File is read and used 
		  as the rules.
    Write Rule Parameters to File - This will write all the current
		  rules to the Rule File.
    Rule File   - The name of the file to use as a source of rules.
		  This file should have one line per rule.  Blank
		  lines and lines that start with '#' will be ignored,
		  so comments may be added to the rule file with '#'.
    Context Ignore - This is a list of symbols.  They will be ignored
		  when trying to determine contexts.
    Premise     - The initial state of the LSystem.  This is the state
		  of the LSystem at generation 0.
    Rule #	- A rule to apply to the LSystem.
    
See also: PolyWire
