Tutorials

1. How to draw basic shapes with SUMMON (01_basics.py)
2. How to use transforms: translate, rotate, scale, flip (02_basics.py)
3. Hotspots and interactive visualizations (05_hotspots.py)
4. more to come...

How to draw basic shapes with SUMMON (01_basics.py)

Open and run the example

For an introduction to the basic API of the SUMMON module, let us walk through the code of the first example. This example is included in the source code (download) under the summon/examples directory. To begin, change into the summon/examples/ directory and open up 01_basics.py in a text editor. Also execute the example with following command.

The following visualization should immediately appear in a new OpenGL window.

Navigating the visualization

The following mouse and key-bindings are provided by default in SUMMON. You can use them to navigate your visualization. They can be customized with the set_binding function.

Overview of the example source code

In your text editor, the example 01_basics.py should contain python code similar to the code displayed below. The first two lines of the script import the summon module and all of the basic SUMMON functions (group, lines, color, etc) from the summon.core module into the current environment.

#!/usr/bin/env python-i
# SUMMON examples
# 01_basics.py - basic commands

# make summon commands available
from summon.core import *
import summon

# syntax of used summon functions
# add_group(  )   = adds a group of graphics to the screen
# group(  )    = creates a group from several graphical elements
# lines( x1, y1, x2, y2, ... )  = an element that draws one or more lines
# quads( x1, y1, ..., x4, y4, ... )  = an element that draws one or more quadrilaterals
# color( , , , [alpha] ) = a primitive that specifies a color


# create a new window
win = summon.Window("01_basics")

# add a line from (0,0) to (30,40)
win.add_group(lines(0,0, 30,40))

# add two blue quadrilaterals inside a group
win.add_group(group(color(0, 0, 1), 
                    quads(50,0, 50,70, 60,70, 60,0),
                    quads(65,0, 65,70, 75,70, 75,0)))

# add a multi-colored quad, where each vertex has it own color
win.add_group(quads(color(1,0,0), 100, 0,
                    color(0,1,0), 100, 70,
                    color(0,0,1), 140, 60,
                    color(1,1,1), 140, 0))


# add some text below everything else
win.add_group(text("Hello, world!",     # text to appear
                   0, -10, 140, -100,   # bounding box of text
                   "center", "top"))    # justification of text in bounding box

# center the "camera" so that all shapes are in view
win.home()

Open your first SUMMON Window

# create a new window
win = summon.Window("01_basics")

Creating your first drawing group: a line

All graphics are added and removed from the window in sets called groups. Groups provide a way to organize graphical elements into a hierarchy. The first graphical group added to the window is a line.

# add a line from (0,0) to (30,40)
win.add_group(lines(0,0, 30,40))

The line is created with the lines function, which takes a series of numbers specifying the end-point coordinates for the line. The first two numbers specify the x and y coordinates of one end-point (0,0) and the last two specify the other end-point (30,40). Next, the line is added to the window using the window's add_group function.

Nesting drawing elements with the group command

The next part of the example adds two quadrilaterals to the window with the quads and group commands.

# add two blue quadrilaterals inside a group
win.add_group(group(color(0, 0, 1), 
                    quads(50,0, 50,70, 60,70, 60,0),
                    quads(65,0, 65,70, 75,70, 75,0)))

The arguments to the quads function are similar to the lines function, except four vertices (8 numbers) are specified. In the example, two quadrilaterals are created and grouped together with the group function, which takes an arbitrary number of drawing elements as arguments. Note, both the lines and quads functions can draw multiple lines and quadrilaterals (hence their plural names) by supplying more coordinates as arguments.

Adding color

The third group illustrates the use of color.

# add a multi-colored quad, where each vertex has it own color
win.add_group(quads(color(1,0,0), 100, 0,
                    color(0,1,0), 100, 70,
                    color(0,0,1), 140, 60,
                    color(1,1,1), 140, 0))

Color is stateful, as in OpenGL, and all vertices that appear after a color object in a group will be affected. The color function creates a color object, which can appear within graphical elements such as lines and quads or directly inside a group (see the previous code snippet for an example). Since each vertex in the quad above has a different color specified before it, OpenGL will draw a quadrilateral that blends these four colors.

Easy layout of text

Lastly, an example of text is shown.

# add some text below everything else
win.add_group(text("Hello, world!",     # text to appear
                   0, -10, 140, -100,   # bounding box of text
                   "center", "top"))    # justification of text in bounding box

Once again, the text is added to the window using the window's add_group function. The arguments to the text function specify the text to be displayed ("Hello, world!"), a bounding box specified by two opposite vertices (e.g. the lower left (0,-10) and upper right corners (140,-100)), and then zero or more justifications ("left", "right", "center", "top", "bottom", "middle") that will affect how the text aligns within its bounding box. There are currently three types of text: text (bitmap), text_scale (stroke), and text_clip (stroked text that clips). The bitmap text will clip if it cannot fit within its bounding box. This is very useful in cases where the user zooms out very far and no more space is available for the text to fit. See the example 10_text.py for a better illustration of the different text constructs.

Bring it all into view

The final function in the script is win.home(), which causes the SUMMON window to scroll and zoom such that all graphics are visible. This is a very useful command for making sure that what you have drawn is visible in the window. The command can also be executed by pressing the 'h' key within a SUMMON window. This key comes in handy when you "lose sight" of the visualization.

And much more...

This is only a simple example. There are many more drawing functions:

• text_scale
• points
• lines
• line_strip
• triangles
• triangle_strip
• triangle_fan
• quads
• quad_strip
• polygon
• color
• text
• text_scale
• text_clip

See the remaining scripts in the summon/examples/ for examples of SUMMON's more powerful features. For more documentation, also see the manual and online API documentation.

Next time: Transforms!