PyGeo: a dynamic geometry toolkit

PYGEO QUICKSTART

Contents

Overview

A good place to start for an overview of PyGeo, and its vision of itself, is by reading the PyGeo Overview document.

Dependencies

In addition to the Python interpreter itself, PyGeo is dependant on the VPython http://vpython.org/ 3d rendering environment, as well as either Numeric or NumArray (included with the VPython binary distributions) for fast array processing and linear algebra operations

PyGeo is most thoroughly tested with Python 2.4 and VPython 3.2.9. It is known not to be compatible with VPython 3.3beta, but will be made so after VPython 3.3 is beyond its beta testing phase.

PyGeo is capable of outputting POV-RAY http://www.povray.org/ scene files to allow for high quality rendering of a construction's static state. POV_RAY is free and can be downloaded at http://www.povray.org/download/ PyGeo is tested with POV_RAY version 3.6.

PyGeo is also capable of calling a finished POV-RAY image for display, upon the completion of rendering. The range of potential POV-RAY image output formats that can be displayed by PyGeo is made complete by the installation of the Python Imaging Library, available for free at

return to Contents

Hello Point, Hello Line

A PyGeo construction is created by:

  • importing the PyGeo classes and constants
  • initializing a display
  • creating instances of geometric objects rendered in immediate mode on the display
  • for interactivity, entering a loop in which the display screen will respond to mouse events.

A simple interactive session from the Python interactive prompt(say in IDLE at the Python Shell window)

Hello Point :

>>> from pygeo import *
>>> display=display()
>>> FreePoint(1,4,5)
vector(1, 4, 5)
>>> display.pickloop()

Hello Line :

>>> from pygeo import *
>>> display=display()
>>> p1 = FreePoint(1,4,5)
vector(1, 4, 5)
>>> p2 = FreePoint(5,11,9)

>>> Line(p1,p2)
>>> display.pickloop()

See Construction interactivity for explanation of mouse interaction with the created display scene.

return to Contents

Edit and run environment

While it is possible to create constructions from the Python interactive prompt, for more involved constructions it is desirable to create scripts in a text editor and run them as (Python) *.py files with the Python interpreter.

PyGeo now provides, as a separate download, an editor which should serve well as an environment for the creation and execution of PyGeo constructions.

What is provided is a version of Neil Hodgon's SciTE http://www.scintilla.org/SciTE.html programmers' text editor customized to provide:

  • Syntax highlighting of Python keywords and PyGeo classes, functions, keyword options and constants
  • Autoword completion for PyGeo's exposed geometric classes and functions
  • Calltips for PyGeo's exposed geometric classes and functions
  • Access to Python and PyGeo documentation from the menu system.

Options under the 'Tools" menu item provide for calling the Python interpreter to either check the syntax of the current script, feed back, and exit; or to run the script in full.

There are a myriad of options beyond that of using the PyGeo customized editing environment.

It should be warned that some editors that are themselves written in Python seem to have difficulties running VPython display windows (on which PyGeo depends) - the most frequent problem being the unintended closing of the editor itself when quitting a construction display.

Cross platform editors know to be VPython, and therefore PyGeo friendly, include:

Windows:

  • TextPad. a good, inexpensive shareware Windows programmers text editor http://www.textpad.com/ is easily set-up through its New Document Class wizard of the Configure menu to recognize and run Python scripts.

    The utilities folder of the PyGeo distribution includes a pygeo.syn file which can be used to add PyGeo aware color-highlighting to the Python document class intended to be used to run PyGeo constructions.

A more complete list of Python compatible editors can be found at http://wiki.python.org/moin/PythonEditors

return to Contents

Example and test scripts

The PyGeo distribution comes with an extensive set of example constructions and test construction scripts.

A sensible place to start in a hands on exploration of PyGeo's functionality is through these scripts.

See Examples and test scripts section of the Overview document

return to Contents

Construction interactivity

Once a display has entered into a event loop by a call to the pickloop() method, it will respond to mouse events, allowing interactivity with the construction:

  • Left click:

    • if a pickable point is hit, the point hit will identify itself by enlarging and displaying in Green
    • if no pickable point is hit, all pickable points will respond by flashing larger and displaying in Blue

  • Left drag:

    • a picked point is moved in reaction to a drag with the left mouse button down.

  • Right drag:

    • the scene will rotate around the camera center in reaction to movement with the right mouse button down

  • Middle drag, 2 button drag:

    • the scene will zoom closer or further in reaction to movement with the middle button, or the left and right buttons simultaneously down.

return to Contents

Panel Menu

By default, a creation of a display also creates a separate panel that contains option box and menu options. The creation of the panel can be suppressed by including the expression "panel = False" as a keyword parameter when initializing the display:

  • Information output

    The lower level boxes of the panel display state information, as follows, following the display boxes from left to right:

    • the "name" of the currently picked point, if a label has been assigned to the point.
    • the x,y,z coordinates of the currently selected point
    • the current on/off state of the Trace option (see menu options, below)
    • the current on/off state of the Drag option (see menu options, below)

  • Check buttons and radio buttons:

    • Detail Level:

      when creating a geometric object (i.e. class instance) there is the option to specify a display level using the keyword argument "level=<integer value>", with the level defaulting to "1" in the absence of an argument. e.g.:

      p1= Point(1,17,-3,level=3)

      sets the point p1 to be visible only when Level 3 is checked in the Detail Level check box group

      Multiple and non-consecutive levels of display can be selected and deselected.

      Assigning an object "level = -1" will assure it to be visible at all display levels

    • Drag Constraints:

      to allow control movement, pickable points designed to be freely movable in space (FreePoint, zFreePoint) are at any one time constrained to a particular plane or direction relative to the display coordinate scheme. The Drag Constraints radio button option sets the constraints on the movement on points picked and dragged.

  • Menu - Options

    • Reset to initial:

      returns all picked and moved points to their position at initialization, and resets all dependant objects to their position based on the points' initial positions.

    • Remove tracings

      remove all loci of points and/or lines created via the "tracing" mechanism.

    • Toggle trace on/off

      toggle the state of tracing from its current on/off state as displayed in the information text box.

    • Toggle axis visibility

      toggle the visibility of the representation of the 3d coordinates axes.

    • Toggle drag effect

      the drag effect determines whether the construction attempts to update at each update cycle during the movement of pickable point ("Drag On") or updates only upon release of the dragged point ("Drag Off").

      the menu option toggles the state of the drag option form its current state as displayed in the information text box.

    • Animate

      invoke periodic rendering loops, inducing "animation" of objects (and their dependents) designed to re-position at each rendering loop cycle.

    • Export to Povray

      enter file browser dialogue for export of the visible elements in the scene to Povray scene definition format *.pov

  • Menu - Help

    • PyGeo help

      calls PyGeo main help index in html browser

    • Diagram Instructions

      displays triple quoted (""") text in construction script referenced to the "instructions" keyword in the initialization of the display

    • Diagram Explanation

      displays triple quoted (""") text in construction script referenced to the "explanation" keyword in the initialization of the display

return to Contents

"One of my foreign colleagues gives classes on the esthetics of programming. I advised him to throw away the overhead projector and return to the blackboard. It made him find again the joy of teaching".

Edsger Dijkstra