Cicada documentation

Cicada version 0.2 is a conceptual model intended for evaluation as a proof of concept. It is intended to show that a graphics-oriented Python development environment can be easy for beginners to use, and that Panda3D provides a suitable graphics engine for this purpose. Many desirable features are yet to be implemented. The future development of this project depends on your comments and suggestions. Contact Chris Hilder cj.hilder@clear.net.nz or add a comment at the foot of this page.

Getting started with Cicada

Write Python commands in the writing pane and then click the Do button.

The Cicada interface takes a bit of getting used to because hitting Enter starts a new line; you have to hit the Do button to get anything to happen. Also you have to hit the Clear button if you want to type a new command. This button clears the writing pane (it does not clear the graphics). Otherwise edit the last command until it is the way you want it, then hit the Do button. The benefits of this will become apparent later.

You can start with the classic hello world program if you like. Why not? Type print 'Hello World!' and click the Do button. The command is carried out and the result appears in the Output pane. Exciting? Not!

What about getting the computer to actually do some work? Computers are good at maths aren't they? Type 2+2 and click the Do button. Exciting now? Still not!

Let's talk to the panda. Type forward(100) and hit the Do button. Watch the panda go. Type right(120). And so on. You can keep going like this and draw a triangle.

Let's teach the panda a new trick. Click in the Edit control box and type tri then press Enter. The beginning of a new function definition will appear in the writing pane. Complete it so it looks like this:

Hit the Do button and the function tri is defined. Test it by hitting the Clear button, typing tri(), and hitting the Do button. You should see the panda draw a triangle like this:

We are looking down on the panda. To get a side view, use the View menu and choose Side view. You should see this:

A neat trick when you are working to develop a function like tri() is to put some commands that test the function immediately following the function definition. That way clicking Do will both update the function definition and test it. For example, get the function definition for tri() into the writing pane by popping down the menu in the Edit control box and choosing tri(). Then add the test commands at the bottom (with no indentation) and hit Do. It might look like this:

When you click Do the function is freshly defined and the test commands are carried out. Now it should be apparent why you don't want the writing pane to automatically clear after you click Do.

Workspace management

Once you have created one or more functions they can be saved. Use the File menu. In Cicada a group of functions is known as a workspace and they all get saved together in a single workspace file. This is very similar to a Python module, although the file extension is different and the process for getting something done when a workspace is opened is slightly different. In a Cicada workspace the function startup() is run when the workspace is opened - all you have to do is name one of your functions startup().

There are several example workspaces in the folder called "examples" which is a standard part of Cicada 0.2. Use File menu, Open... to open and explore these workspaces.

Sprite commands

The following is very brief documentation designed to support someone who is familiar with Python.

Move a sprite

A sprite is a 3D object that can be moved around in virtual space. There is a default sprite: that's the panda that you see when you start up Cicada. The moves are all relative to the present position of the sprite. It goes forward in the direction it is currently facing, and turns right from the direction it is currently facing, and so on. This type of relative sprite movement is known as 'turtlegraphics' after the original Logo turtle, although Cicada takes it into 3 dimensional space. 

forward(steps)
back(steps)
right(angle)
left(angle)
up(angle)
down(angle)
rollLeft(angle)
rollRight(angle)

see the workspace simple2D.cicada for examples

Draw with a sprite

As a sprite moves around it can draw wireframe graphics in 3D. When the pen is down it draws, when the pen is up it moves without drawing. You can also draw by stamping copies of the sprite's persona onto the drawing. Pens going up and down, and rubber stamps are all paper-based metaphors. We have taken the paper-based ideas and extended them into 3D space without changing the words we use.

clear() - clears the sprite drawing, and resets the sprite to co-ordinate
             position (0, 0, 0) facing along the positive Y-axis.
penDown()
penUp()
isPenDown()
stamp() - like a rubber stamp, makes a copy of the sprite's persona and
               adds it to the drawing
 
see tree3D() in  the workspace recursiveTree.cicada for an example of stamp()
 

Animate with a sprite

Sprites take time to get from place to place, and this allows you to use their movements to create simple animations. You can alter their speed, size, and whether or not they are visible

setSpeed(speed) - speed is in sprite steps per second. Use setSpeed(0)
                               if you want the sprite to draw instantaneously.
setSize(scaleFactor)
getSize()
show()
hide()
isShown()
 

Animate drawings

It is often hard to see a 3D drawing properly unless it moves, the commands spin() and toss() set the drawing moving. The speed parameter is a bit of a misnomer; it is the number of seconds for a complete cycle so is more properly 'slowness'.

spin(speed)
toss(speed)
stopSpinning() - cancels the spin() or toss() command
wait(seconds) - waits the given number of seconds
 

Surfaces with a sprite

Wireframe drawings are not much fun. 3D shapes need to be made of surfaces. Cicada enables you to draw triangular surfaces, which you can join together to make surfaces of any shape. You move a sprite to three different locations in space, setting A, B and C as you go. Then the command triangle() draws a triangular surface using those three points. The surface either uses the current colour, or a texture if one has been set.

setA() - sets the point A to be the current location of the sprite
setB() - sets the point B to be the current location of the sprite
setC() - sets the point C to be the current location of the sprite
triangle() - draws a triangular surface connecting the points
                  A, B, and C which were earlier set
setTexture(texture) - any image file can be used as a texture; e.g. setTexture("bricks.bmp")
 
see the workspaces simple3D.cicada and cube.cicada for examples
 

Colour

Colour names are the X-11 colours, basic ones are: white, silver, gray, grey, black, navy, blue, aqua, teal, green, olive, lime, maroon, red, orange, yellow, purple, and fuchsia. Each name must be preceeded by "colour." for example setColour(colour.red)

setColour(colour)
getColour()
 

Sprite text

write(text)
setFont(font) - in version 0.2 the only fonts available are century, chiller, and block; e.g. setFont(century)
 

More sprite geometry

lookAt(otherObject)
distanceTo(otherObject)
home() - moves the sprite to the home position, co-ord (0, 0, 0)
               facing along the positive Y-axis.
setPos(x, y, z)
getPos()
setHeading(heading)
setPitch(pitch)
setRoll(roll)
getHeading()
getPitch()
getRoll() 
 

Sprite adopting a new persona

adopt(persona) - in version 0.2 there are five personas to choose from: panda, dancer,
                            goose, car, and r2d2. Select a persona like this: e.g. adopt(goose)
adoptDrawing() - adopting your own drawing as a persona
                            is the basic technique for animating a drawing in Cicada
adoptDrawingFrom(otherSprite)
merge(persona)
mergeDrawing()
mergeDrawingFrom(otherSprite)
 
see the workspace personas.cicada for examples
 

Support for recursion, multiple sprites, and threads

clone()
drawOn(target)
whenStarted(fn)
start()
 
see the workspace parallel.cicada for examples
 

Communicate with the user

say(something) - displays a message box
ask(question)   - returns true/false according to whether the
                           user answers yes or no
askString(question) - returns the string of text that the user
                                  types in response to the question
 

 

Last edited by System Administrator .
Page last modified on Thursday 17 of February, 2011 10:48:54 NZST.
The original document is available at http://teach.hilderbuild.com/tiki-index.php?page=Cicada%20documentation