How to Use the Spirograph

 

Setting-up the Spirograph

To run Spirograph in the lab under Linux, do the following:
  1. Open up a shell (via the icon with the seashell at the bottom of your screen).  It should open to your home directory .
  2. Create a directory from which to run Spirograph by entering: 
    mkdir Spirograph
    Then, change to that directory by typing: cd Spirograph
  3. Save the Spirograph library Spirograph.jar to this directory. Save the bsh library bsh-1.0.jar as well.
  4. Start JBuilder and create a new project. Open up the properties menu and add both Sprirograph.jar and bsh-1.0.jar as libraries.
  5. We now have to tell JBuilder which class is to be the main class. Spirograph.Main is what we are looking for, this will be in one of the properties menus.
  6. Hit the green arrow, be patient, and the Spirograph will start!
When you start up the Spirograph program, two windows will be displayed. The area with the two large text boxes in it is the code editing area, in which you will write statements that will control the Spirograph. The window with the dot in the center is the Spirograph itself.  You may want to move the windows so that you can see both windows at the same time. If there are no buttons at the bottom of the Spirograph window, just grab the lower edge of the window and make the window larger. Java sometimes hides the buttons when resizing the window......

Editing Code: The Basics

If you press the Start button in the Spirograph window, you will notice that nothing happens.  This is because the motion rules of the Spirograph have not been loaded yet.  To create a rule, type into the appropriate text box in the Code Editor, and then press the "Load Horizontal (or Vertical) Code" button.  This will generate a .java file using your code, compile it into a .class file, and then use this code as the corresponding motion rule for the Spirograph.  (Note: the Spirograph has been designed so you can load new code even while it is running.  However, for more reliable operation, we recommend that you press the "Stop" button before compiling, and then press "Start" again after compiling.)

Messages during compilation are displayed in the JBuilder run-time window.  If there are no errors in your code, a message should appear that says, "Compilation successful."  Otherwise, error messages from the Java compiler will be displayed. You can then edit your code, and try again.

Try typing a simple statement such as return 10; and compiling it.  Try typing an erroneous statement such as return "Ten" and observe what happens.  (What is wrong with the latter return statement?)  Load simple rules for both axes, and start the Spirograph.  Can you make the dot go to position (10, 20)?

Using the Horizontal and Vertical Rules

If you click on the button that says "Advanced Programing Options" in the code editing area, a window will appear with five buttons to click on. We'll start by looking at the top three of these buttons. If you click on the button that says, "Use Horizontal rule for both rules." The vertical text area and "Load" button will be grayed out. The next time you press the "Load" button, any code you enter in the Horizontal text area will now be used to control both the horizontal and vertical motion of the dot. You can also choose to use the Vertical rule instead for both rules.  To go back to using both rules, click on the button that says "Use seperate rules", and then click on both "Load" buttons.

Using Names in Your Code

System-Provided Names (Parameters)

In your code, you may make use of the following names, which are of type double: For example, if a rule is being used as the horizontal rule, then pos would return its x coordinate, and vel would return its velocity in the x direction.

Temporary Storage Names (Variables)

You can also create your own names by declaring them in your code.  These names can be used to hold values throughout a single application of a rule.  The next time the rule is applied, however, the values of these variables are lost.  These types of names (also called variables or local variables) are useful for providing temporary storage during computations.

e.g.,  double nextPos;
    nextPos = pos * 2;
    return nextPos;

Long-Term Storage Names (Fields)

Spirograph also allows you to create names whose values are preserved across different applications of a rule.  These are called fields.  To create a field, pop up the "Advanced Programing Options" menu and click on a button to edit either the Horizontal or Vertical fields. Another small text area should appear in the Code Editing window. You can declare and/or define fields there.  (If your window gets messed-up, just resize it by dragging a side or corner of the window, and it should fix itself.)  Note that you can initialize a field by using a definition (a declaration combined with an assignment).  In general, it is considered good practice to initialize your fields to a reasonable initial value.

Example:

Fields:    int myInt = 5;

Rule:     myInt = myInt + 1;
      return myInt;

(Can you predict what this code would do?  Think about it first, then try it.)

Using the Spirograph

At this point you should be ready to write your own code to control the Spirograph. Try to write code that will produce interesting patterns, and see if you can predict ahead of time what the results of your code will be.  To use the Spirograph, make sure you have loaded your code, and compiled it successfully.  Then, press the "Start" button on the Spirograph window, and watch the dot move.  You may stop the dot by pressing the "Stop" button.  The "Reset" button allows you to do such things as clear the lines drawn by the Spirograph, and/or put the ball back in the center.

Using the Advanced Environment Options

The Spirograph has several Advanced Environment Options.

Wall Properties

You can enable or disable certain properties of the Spirograph window's edge.

Control Mode

You can select whether the values returned by the rules are used to determine position, velocity, or acceleration.  Note the following:

Mouse Mode

You can choose to use the mouse to reposition the dot or to add gravity sources.  Or, you may choose not to use the mouse at all.  By default, the mouse lets you reposition the dot in the Spirograph.  Adding gravity sources is an interesting advanced feature which we will not use for the lab exercises.  You are welcome to play around with them yourself, however.

Velocity

These entry boxes allow you to set the velocity of the dot.  Enter the desired values first, then press "Set Velocity" to actually effect the change.

Managing Your Code

Spirograph does not have explicit File management features.  However, there are several ways to save your work, if you want to.

The Rule.java files

The text that you type in the Code Editor window is taken by Spirograph and inserted into a template that looks something like this:

public class HorizRule implements Accelerator {
// Fields code goes here
public double act (double pos, double vel, double otherPos, double otherVel, double maxPos) {
// Rule code goes here.
}
}

Everytime you press the "Load" button, Spirograph generates either HorizRule.java or VertRule.java (depending on which rule you're loading), and then tries to compile it.  The .java file is stored in the directory from which you ran Spirograph, and remains there even after you exit Spirograph.  Thus, you can do whatever you want with this file, such as, copy it, rename it, print it, etc.

When you run Spirograph, it checks for the existence of these files, and loads the Code Editor window with the appropriate code from these files, if there is any.  Thus, one way to save and load back files would be as follows:

Another way to maintain different versions of your code is to use the commenting features of the Java language.  In Java, a anything to the right of a  // is considered a comment and is not compiled.  The intent of this feature is to allow programmers to document their code with useful comments.  However, you can also use this feature to allow you to get different behaviors from a single source code file.  Specifically, you can have a file that contains code for several different behaviors, and with all but the desired behavior commented out.  Although this maybe a useful trick for simple and short code snippets such as what you will be writing for this Spirograph Laboratory, please note that in general, doing this is not really good programming practice, as it can result in messy and hard-to-read code.
 

Go back to the Exercise 1 page.