Fish 'n' More 2/fishmore-publicdomainlibraryvol.ii1991xetec.iso/fish/applications/polysys/polysys.docs

Text File | 1990-10-23 | 24KB | 462 lines

/* PolySys 1.0 ©1990 by Terry W. Gintz */

PolySys is an extended version of the 0L-system (string rewriting) described
in The Science of Fractal Images (edited by Pietgen and Saupe.)  The basic
algorithm has been expanded and modified extensively, and looping commands
similiar to those found in other Turtle graphics systems (Logo, etc) have
been added.  Support for three-dimensional drawing, with perspective, is also
included in PolySys.  To enable the program to run on an Amiga 500 without
extra memory, an alterate method of string interpretation has been
implemented, using recursion.  String size is kept to a minimum, while the
axiom is interpreted character by character.

For those who are not familiar with L-systems, a discussion of their basic
features and how they differ from other turtle graphics is a good starting
point.  Lsystems have as their base an axiom, which is a string of character
commands, or a single character.  The character can be a command in itself,
such as 'F' for forward, or it may be a production rule, which is a string of
commands also.  The axiom and production rules are created and edited with
separate editors.  When the axiom is 'run', the axiom is scanned for
commands and/or rules.  Recursion is used to substitute where necessary a
production rule string for a single character, to the depth specified at
runtime.  In 0L-systems, quite long character strings can be built this way
and then executed.  Once the string is built, it is then stripped of
non-commands and executed without displaying the commands on the screen.
The size of the drawing object is thus established and it is then scaled and
drawn on the screen.  The first significant difference from other turtle
graphics systems is now apparent: self-scaling.  The object will never
overrun the screen boundaries.  Objects can be displayed to the limits of
the window, regardless of window size.  PolySys uses a 640X400 hi-res
screen, but any resolution is possible.

L-systems have a stack available to keep track of turtle position and
variables whenever it is necessary to return to a particular point in the
drawing.  This is useful for producing tree structures and other branching
patterns.  PolySys puts on its stack the turtle postion, headings,
linestyle, and color information.

The third significant difference between L-systems and other turtle graphics
interpreters is in its handling of recursion.  In L-systems, recursion is a
built-in feature.  You only need to specify the level of recursion, and the
system does its string interpretation to that level.  PolySys uses recursion
to call its own interpretation routines, and thus eliminates the need for
lengthy strings to interpret.

The price for the above built-in features is speed.  Lsystems can never be
as fast drawing a dragon curve, for instance, as a dedicated dragon-drawing
program.  On the other hand, fractal generators have trouble matching the
speed of L-systems where branching patterns are involved.  There is no need
to recurse backwards to reach a branching node in L-systems:  just pop the
stack, and you're there.  PolySys is capable of rendering polygons in three
dimensions, but cannot match the speed of a dedicated 3-D modeler such as
PageRender3D.  There is no hidden-line removal or shading included in
PolySys, except for solid area fills or flood fill.  The 3-dimensional
features can be used to produce more realistic looking plants than
a 2-dimensional L-system could produce.  L-systems such as PolySys offer the
user a chance to experiment with a very different approach to graphics
production.  The author has included many examples of possible
approaches to using PolySys, but these are only initial exercises, like
tuning a guitar.  Productions of imaginative insight remain to be created
and explored.

The following is a decription of the features of PolySys, starting with
menus and windows, and concluding with available commands.

The Menus:

The Main or Project menu:

'New' -- Erases the current axiom and production rules from memory.  Will
ask for confirmation before doing so.

'Clear' -- Clears the drawing window to the color specified by the
background menu, one of 16 colors.

'Draw' -- Opens the runtime window, which includes gadgets to set rotation
angles, perspective, scale of drawing, and depth of drawing, etc.  This
window has options to draw or redraw the current axiom, or draw a
perspective version of the axiom (if in 3-D mode).  You can abort the drawing
at any time by clicking in the drawing window with the left mouse button.

'Save' -- Saves the current axiom and production rules, background, rotation
angles and depth.  Scale and perspective are not saved.  A custom icon is
created for each data file, that can load PolySys and draw itself from the
Workbench.  You can save an axiom without production rules, or rules without
an axiom, but you can't load and draw the latter.

'Load' -- Loads an axiom and its associated data, and runs the axiom, if not
NULL.  Does not automatically clear the screen each time an axiom is loaded,
so you can display multiple axioms on the drawing window.

'Save' and 'Load' use a Charlie Heath file requester to save and retrieve
data files.  Enter the directory name into the upper box of the requester,
or leave blank for the current directory.  Click on the file you wish to
load, or enter a name in the file name box.  Click on Okay to load the file
or click Cancel to abort the operation.

'Quit' exits the program.

The Edit menu:

'Axiom' -- opens the axiom editor window.
'Rules' -- opens the rules editor window.

The Background menu:

You set the background color to any of 16 colors specified by the elements
of this menu.  Does not automatically clear the screen.  You have to use the
choose 'Clear' on the main menu to clear the screen to the color selected.
Alternately, see use of the axiom/rule command 'c'.

The Windows:

The main drawing window is a hi-res interlaced window 640X400.  Smart
refresh is used to save the current image while other windows are in use.

The runtime draw window has gadgets to set projection angles in 3-D mode.
These are not used in 2-D mode.  You enter the level of recursion into the
level gadget.  The maximum level of recursion is limited to 50.
Use the scale slider to set the size of the drawing, .01 to full-size.
Use the perspective slider to set the amount of perspective
desired, if in 3-D mode.  A range of 1-30 is allowed, with 1 being the
maximum perspective.  The perspective option is available only after the
figure has been drawn without perspective.  (The parser needs to know limits
on the figure size to calculate perspective.)  You don't have to wait for the
first drawing to finish to use perspective.  Click on Draw to recompute
and draw the current axiom.  Click on Redraw to redraw the figure after it
has been drawn once.  Use this option after changing background, or clearing
the screen.  Click on Perspect, if enabled, to draw a perspective version of
the current axiom.

The axiom editor:

Enter the maximum number of angles in the number box, 1-360.  Enter an
axiom, up to 55 characters in the axiom box.  Click on Okay to set the new
axiom into memory.  Click on Cancel to revert to the previous axiom.  You
must have a number in the number box >0, for the Okay option to work.
Entering an axiom enables the Save and Draw options on the Main menu.  See a
description of the available commands, if unsure what is acceptable as an
axiom.

The rules editor:

The top row of gadgets are the command line gadgets, and the string gadgets
are used to enter production rules and labels.

The string gadgets:

'Rule' -- enter up to 45 characters for each production rule.

'ARule' -- enter up to 45 characters for an alternate production rule, if
a number greater than 0 is entered into the Prior gadget.  Otherwise, the
ARule is added to the Rule for a double-long production rule.

'Prior' -- sets a priority from 0-9 for the ARule.  A random generator is
then used to decide which rule to use at runtime.  If the random number is
less than the Priority then the ARule is used (even if NULL.)  If Prior is
set to zero, the main Rule is always used, then the ARule, if any, is
executed also. A buffer of 10000 bytes is set aside for random elements at
runtime.  This is used to match the drawing created while sizing it, so that
the drawing will not go off-screen during actual plotting.

'Label' -- the label for the production rule.  Must be ASCII, non-blank, and
contain no CTRL key sequence.  For rules that will be called recursively,
it's best to use Upper Case letters for the label, as all lower case letters
are used in commands.  Exceptions to this are the labels that you wish to be
commands that change themselves recursively, such as 'F'.  E.g.  the rule may
be F='FFF'.  At each level of recursion, the forward command triples in
length, and a line is drawn three times as long as the previous level.

The command line gadgets:

'Add' -- adds whatever production rule has been entered into the string
gadgets, if the label does not duplicate a label already in use.  Up to 10
rules can be entered.  The window below the string gadgets displays the
current production rules in use.

'#' && 'Recall' are used in conjunction to edit a previously added rule.
Enter the number of the rule, as displayed below, into the # gadget and
click on Recall.  The rule is entered into the string gadgets.  This enables
'Change' and 'Delete' to change or delete the rule.  An extra step here
prevents changing or deleting the wrong rule by mistake.  Hint:  you can also
change the rule and then Add it in the same operation, if the label is
changed.  Use 'Cancel' to change a another rule, if you don't really want
to change or delete the rule you Recalled. (# gadget is disabled during a
Recall operation.)

'Cancel'  -- cancels the recall operation.

'Insert' -- inserts a rule before the numbered rule as entered in the #
gadget.  You can insert a rule after recalling and changing it, too.  You
can't insert a rule with a label already in use.  You must add at least one
rule before you can insert a rule.

'Done' -- terminates the edit-rule session and closes the edit rule window.


Axiom and production rules can be composed of the following commands:

Most of the original command set is included: '+','-','F','[',']'.

   '+' -- turn right by a set angle.  E.g.: '+45' would turn the turtle
heading right 45 degrees (assuming 2-D mode and the number of possible
angles is 360.)  A '+' followed by a non-numeric command defaults to 1, or
360/[number of possible angles.]  Turtle headings are based on a maximum
number of turnings, set with the axiom editor.  The number of angles can be
set from 1 to 360.  Thus, irregular angles such as PI/7 can be implemented
as 14.

   '-' -- turn left by a set angle.  E.g.: '-' followed by a non-numeric
command turns the turtle heading left 360/[number of possible angles]
degrees (assuming 2-D mode.)

   'F' -- go forward a set length, and draw a line there from the original
position.

   'D' -- same as 'F'.  Used when 'F' is used as a production rule.  E.g.
F='FFF'.  Here, F becomes FFF at every stage of recursion, while D remains D
(if not defined in another production rule.)

   '[' -- save turtle position and variables on stack.

   ']' -- retreive turtle position and variable from stack and decrement
stack.

   'm' -- originally 'f', move a set length forward without drawing.
   (Another difference from other turtle graphics -- no penup or
pendown intermediate commands.)

   'n' -- same a 'm'.  Used when you need a single move command and 'm' is
defined as a production rule.

   '|' (turn back, or turn by 180 degrees) is not implemented, because that
would make no sense in 3-dimenional mode.  Use '+180' or the like, depending
on the number of possible angles set.

In addition, the following commands are available:

   'c' -- clear the screen to the color specified on the background menu.

   'o' -- turn on 3-dimenional mode; must be the first character in the
axiom to work.

   'p' -- set line color to the color specified by the following character or
characters.  (Palette is limited to 16 solid colors.)  E.g.: 'p10' would set
A and B pens to the color specified by the tenth element of the colortable.

   'b' -- set B Pen to the color specified by the following character or
characters.  (136 colors are possible with dithering.)  E.g.:  'b1' would
set the B pen to the color specified by the second element of the colortable.
Dithering is based on an alternating dot pattern.  Linewise the pattern is
ABABAB (A pixel B pixel etc), while a dithered fill alternates ABABABA with
BABABABA.

   '(' -- begin an area fill at present position -- each subsequent drawing
position is added to the fill buffer until the limit of the buffer (1000
points) or until a ')' is encountered.  If the limit of the fill buffer is
reached before a ')' is encountered, the area is closed and filled, and a
new buffer is started from that position.  If a ']' or 'm' is encountered
before a ')' the area is also closed and filled and a new area fill started.

   ')' -- closes the area fill and fills the area (if preceded by '('.)

   'w' -- set line width to the width specified by the following character
or characters.  Width is limited to one half the drawing height -10 (or 190
for a full-sized drawing.)  The width command is used mainly in
2-dimensional mode, as it is a line-implemented rather than
pixel-implemented width.  It will produce uneven results in 3-dimentional
mode.  E.g.: 'w10' would make the current line width 10.

   'l' -- set line length to the length specified by the following
character or characters. E.g.: 'l10' would make the current line length 10.

   's' -- scale length by the factor specified by the following character or
characters.  E.g.: 's1.06' would multiply the current drawing length by 1.06.

   'd' -- delay execution of the next command by the delay length specified
by the following character or characters.  Delay time is specified in
fiftieths of a second, limited to 999 fiftieths or 16.65 seconds maximum.
For example: 'd60' would produce a delay of 1 second.

   'r' -- repeat the execution of the following commands by the number
specified by the following character or characters.  The default is 1, or
one repetition.  For example: 'r5' would repeat a loop 5 times.

   'rv' -- repeat the execution of the following commands until the current
heading is reached again.  Used to create turtle graphics subroutines that
stop when the the total turning is a multiple of 360 degrees.

   '@' -- end of repeat loop.  Repeat loops can be nested to a level of 10.
You should begin and end a repeat loop inside of the same production rule
or axiom, to avoid potential problems with the interpretation of that loop.
Since recursion is used to interpret a production rule character by
character, the '@' can only send the interpreter back to the beginning of
that loop.  Trying to get back to an axiom's repeat loop using a '@' from a
production rule will trigger a syntax error.  Repeat loops that follow each
other should be separated by a delimiter.  E.g.: 'r4!rF@@'.  The '!' between
'r's  is necessary to allow the parser to set the repeat counter on the
previous repeat loop and the return point of that loop before beginning the
next repeat loop.  (Defaults or buffer values are set when non-numeric
values are encountered.)


   'h' -- set the variable specified by the next character (must be a lower
case letter a-z) to the value specified by the following character or
characters.  E.g. 'ha2.5' would place the value 2.5 in 'ha'.  All variables
are initiallized to 0 each time the axiom is run.

The 26 possible 'h' variables may be used to set line length, line
width, scale, palette and B Pen, and repeat loop counters.  For example:
"pha" would set the drawing color (pens A and B) to the value contained in
ha (assuming a valid number is contained in ha.)  The syntax is 'chx', where
'c' is the basic command and 'hx' is any one of 26 floating-point variables.
'h' variables may also be used with '+' and '-' to make turnings dependent on
variables.  E.g. '+hb' would direct the turtle to turn its heading right by
the value contained in 'hb'.  It is necessary to add a delimiter in
front of the 'h' variable, if it follows another command and it is not
intended to extend that command.  E.g. '+hb1' should be entered as '+!hb1'
to prevent misinterpretation by the parser.  Also, watch out for dangling
commands that could be interpreted as extended commands from axiom to rule
or rule to rule.  At runtime, the parser looks at axioms and rules as if one
long string, even though they look separate.

   'f' -- flood fill starting at the current position, with the current
pen colors.  Should be preceded by a few 'm's, to move the drawing
position off a previously drawn line to the area you want to fill.  E.g.:
'mmmf' would move the drawing position three lengths and fill outward any
pixels the same color as the drawing position and not the same color as the
drawing pen.

Extended command set:

   The following extensions of the previous commands are available:

   '*' -- multiply the previous command by the following variable.  Can be
used with 'p', 'b', 'w', 'l', 'h', and 's'.  E.g.: 'l*a' multiplies the
line length by the value contained in ha.  Note that the 'h' is not used in
any of the extended commands to designate the variable (except for the
variable 'hh'.)  A value added to an integer unit, such as line width, is
added as the integer value of the variable.

   '+' -- add to the previous command the following variable.  Can be used
as '*'.  E.g.: 'w+a' adds the contents of 'ha' to the current width.

   '-' -- subtract from the previous command the following variable.  Can be
used as '*'.  E.g.: 'ha-b' subtracts the value of variable 'hb' from 'ha'
and stores the result in 'ha'.

   '>' -- if the value contained in the previous command is greater than the
value of the following variable, set the previous command's value to either
1.0 or 0 (0 if the previous command was 'p','b' or 'h'; 1.0 if the previous
command was 's','l' or 'w'.)  E.g.:  'p>a' -- if the current drawing pen A
is greater than the value of 'ha' set the A and B pens to 0.

   '<' -- if the value contained in the previous command is less than the
value of the following variable, set the previous command's value to either
1.0 or 0 (0 if the previous command was 'p','b' or 'h'; 1.0 if the previous
command was 's','l' or 'w'.)  E.g.:  'p>a' -- if the current drawing pen A
is less than the value of 'ha' set the A and B pens to 0.

   '=' -- if the value contained in the previous command is equal to 0 or
1.0 (0 if the previous command was 'p','b' or 'h'; 1.0 if the previous
command was 's', 'l' or 'w') set the value of the previous command equal to
the following variable.  E.g: 'l=s' -- if the line length is equal to 1.0
then set the length equal to the value of 'hs'.

Thus, using the previous extended commands, any incrementing or decrementing
loop involving color or line style can be set.  E.g.: 'r4w+aw>bw=c@' -- add
the value of a to the linewidth; if the line width is greater than 'hb' set
it equal to 'hc'; repeat this loop 4 times.

Additional extended commands apply to 3-D mode:

   'r' -- roll the specified angle.  E.g.:  '+45r' rolls the current heading
45 degrees right (assuming the maximum number of turnings is set to 360.)
Rolling is the same as rotating the x axis and y axis around the z axis, or
tilting sideways.
   'p' -- pitch the specified angle.  E.g.: '-hap' pitches the current
heading left by the number of degrees equal to the value of 'ha'.
Pitching is the same as rotating the x axis and z axis around the y axis, or
tilting forward or backward.
   'y' -- yaw the specified angle. E.g.: : '+y' yaws the current heading
right one degree (assuming the maximum number of angles is set to 360.)
Yawing is the same as rotating the y axis and z axis around the x axis, or
spinning the figure on the line of projection.
Yawing must be followed by pitching or rolling to notice any change in
heading.  Only 'p' and 'r' update the 3-D turtle heading directly.
Yawing is useful for spinning an object inside of a repeat loop, to create
multiple images of the object on screen.  'r' and 'p' are sufficient to
draw the object's initial view.
   Either 'r','p' or 'y' must be used with the heading commands '+' and '-'
when in 3-D mode, or a syntax error will occur.

Syntax errors that occur during runtime are displayed by changing the
background color to an error color and flashing the screen.
The possible errors are as follows:

   color            error
     0 -- palette incorrectly set via 'h' variable (<0 or >15 or h
designation is missing -- 'h' followed by a label that is not a lower case
letter.)
     1 -- back color incorrectly set via 'h' variable (<0 or >15.)
     2 -- random elements exceed 10000, the current limit.
     3 -- 'h' variable incorrectly set (designation missing or buffer length
exceeded -- >9 digits)
     4 -- '+' variable incorrectly set (h designation missing; 3-D extended
command missing ('r','p',or 'y'); buffer length exceeds 9 digits, or an 'h'
variable was used whose value is greater than the maximum number of angles
set with the axiom editor.)
     5 -- '-' variable incorrectly set (h designation missing; 3-D extended
command missing ('r','p',or 'y'); buffer length exceeds 9 digits, or an 'h'
variable was used whose value is greater than the maximum number of angles
set with the axiom editor.)
     6 -- 'l' variable incorrectly set (h designation missing/ buffer length
exceeds 9 digits.)
     7 -- 's' variable incorrectly set (h designation missing/ buffer length
exceeds 9 digits.)
     8 -- 'w' variable incorrectly set (h designation missing/ buffer length
exceeds 9 digits.)
     9 -- 'r' variable incorrectly set (h designation missing/ buffer length
exceeds 9 digits.)
     10 -- repeat loop is broken (user tried to use '@' to end an axiom
repeat loop from a rule, etc).)
     11 -- stack overflow (stack exceeds 60.)
     12 -- stack underflow (attempted to pop stack that was already zero.)

Errors that do not cause a syntax error are:

   Nesting repeat loops to a greater depth than 10 ('r' ignored.)
   '@' without 'r' (ignored.)
   'r' without '@' (no repeat.)
   '[' without ']' (stack incremented, unless stack exceeded.)
   '(' without ')' (fills object at end of drawing.)
   ')' without '(' (ignored.)
   Delays greater than 999 (delay buffer truncated to 3 digits.)
   Fill buffer would exceed 997 (area fill ended and restarted at 0.)
   Forever loop ('rv' where the angle of turning never gets back to where it
started.  Note: you can stop any drawing at any time by clicking in the
drawing window with the left mouse button.)


Bibliography:  suggested reading for studies in LSystems and turtle graphics:

   The Science of Fractal Images, edited by Peitgen and Saupe, 1988
Springer-Verlag New York (Appendix C)

   Turtle Geometry -- The Computer as a Medium for Exploring Mathematics, by
Harold Abelson and Andrea diSessa, 1981 The Massachusetts Institute of
Technology

Any questions, comments or donations for PolySys should be address to:

Terry W. Gintz
4237 Marcum Lane
Eugene, Or 97402

A donation of $20 for PolySys gets you the documentation to all my current
programs, plus additional help with PolySys if you need it, plus any of the
other programs for $5 off their suggested price, plus upgrade privileges for
$10.