Python Programming

Python is an object-oriented scripting language. Its design mixes software engineering features of traditional languages with the usability of scripting languages. Python scripts can be written that interface with VrOne through VrOne/Python classes. The VrOne/Python classes allow full access to the VrOne database and interactive mapping features. Python is a great way to extend the capabilities of the existing VrOne collection applications. For example, a Python script could be written to place symbols on the ends of a line each time the line is saved. (See the example AddPosts.py)

Python is a full-featured programming language and you should have prior programming experience, but compared to other programming languages, the core Python language is amazingly easy to learn. The new Python programmer should expect to be coding significant Python programs in a matter of days. If you know C, C++, Pascal, BASIC, FORTRAN or Java you will be writing Python in minutes.

From a features perspective, Python is something of a hybrid. Its tool set places it between traditional scripting languages such as Tcl, Scheme, and Perl, and systems languages such as C, C++, and Java. Python provides all the simplicity and ease of use of a scripting language as well as the more advanced programming tools typically found in systems development languages.

For many, Python’s combination of rapid turnaround and language simplicity makes programming more fun than work. To run a Python program, you simply type it and run it. There are no intermediate compile and link steps. As with other interpreted languages, Python executes immediately, which makes for both an interactive programming experience and rapid turnaround after program changes.

Python is an object-oriented language, from the ground up. Its class model supports advanced notions such as polymorphism, operator overloading, and multiple inheritance. Yet, iin the context of Python’s dynamic typing, object-oriented programming (OOP) is remarkably easy to apply. In fact, if you don’t understand these terms, you’ll find they are much easier to learn with Python than with just about any other OOP language available. In most cases, the new programmer will find that task oriented object-oriented programming is clearer and easier to implement than older procedural programming methods. If you are a new programmer and unfamiliar with OOP, look at the examples to see how clear they are before going back to school.

Although VrOne comes with all the necessary software to run Python scripts within VrOne, the entire system can be downloaded from the Internet for free.

The VrOne/Python programmer should have some prior programming experience with Python or other languages such as C, C++, Pascal, BASIC or Java. This is not an absolute requirement, but the Python programmer should be ready to learn about variables, looping, conditional branching and other basic programming concepts. There are several good programming books on Python available at local bookstores such as Barnes and Noble or online at such sites as www.amazon.com.

Since VrOne/Python gives full read/write access to the VrOne database, you should understand the VrOne database and data structures.

Although the Python interpreter is embedded in VrOne and no other software is required to run Python scripts, it is recommended that the user download the Python development. Python is freely available for download from www.python.org. Versions are available for UNIX, Windows, Macintosh, and Java. In addition, this site includes links to documentation, how-to guides, and a wide assortment of extension modules.

VrOne/Python scripts are written using any text editor and stored in the \vr\python directory. Scripts may be stored in other directories and those directories may be entered as a File Path in the Vr Configuration program. Python scripts are started in VrOne by entering the word Python, Pyt or Py and the script name. For example Py AddPosts. If “Require PY command to run Python scripts” is turned off, you can simply type the name of the Python script to run it (assuming there is not a built-in command, function key, or macro of the same name).

It is also possible to pass arguments to the Python scripts from the command window. Any items added to the command line while Python Scripts are running will show up in the VrArgs global list variable. Arguments must be separated by spaces. If an argument contains spaces it must be surrounded by quotes. For example, to run a python script named “drawcircle” that takes arguments for the center point and radius you would type “py drawcircle “10.0 10.0 20.0” 150.0”. In this case the VrArgs variable will contain two elements, and if printing the VrArgs variable will display the following: [‘10.0 10.0 20.0’, ‘150.0’].

When VrOne starts, a Command Prompt window starts with it. This Command Prompt window displays output from a Python script. Any errors which occur during the execution of a script it is displayed in this window. During development, it is recommended that this window be left partially visible so any output can be seen.

Python classes have been developed to facilitate the interfacing and communication between a Python script and VrOne. These classes are:

PyVrWs	Manages VrOne file (workspace) queries and some file operations.
PyVrLine	Holds and manipulates VrOne line data including loading lines from a file.
PyVrSym	Holds and manipulates VrOne symbol data including loading symbols from a file.
PyVrText	Holds and manipulates VrOne text label data including loading text labels from a file.
PyVrPunt	Holds and manipulates VrOne point data.
PyVrGeom	Coordinate geometry routines
PyVrGui	Graphical user interface and miscellaneous system routines
PyVrDtm	DTM routines
PyVrDtmMgr	DTM Surface Management routines
PyVrGr	Graphics routines for drawing directly to graphics windows, and querying cursor state.
PyVrLayer	Layer management routines
PyVrCfg	Allows various VrOne configuration parameters to be viewed and changed.
PyVrMenuKeys	Displays standard menu keys dialog.
VrPromBox	Creates a dialog box with programmable entry fields (prompts) to allow entry of parameters.
PyVrApp	Provides a way to write true event-driven python scripts that have the look and feel of a standard VrOne application.
PyVrImgMgr	Image management routines.

The following examples offer a starting point for VrOne/Python programming. These examples are delivered with each version of VrOne. If you modify and use one of these examples it must be renamed or moved to another directory so it will not be overwritten during the installation of a new VrOne release. The examples are found in the vr\Python directory. NOTE: Tab stops for the example Python (.py) files are set to three.

Program Name	Demonstrates	Description
AddCircle.py	PyVrSym, PyVrLine	Loads the last symbol and draws a star type line around the symbol.
AddPosts.py	PyVrLine, PyVrSym	Loads the last line and adds symbols to line ends.
ChangeLines.py	PyVrWs, PyVrLine	Loads all the lines in current workspace, changes the layers and graphic pointers and re-records them.
ChangeSymbols.py	PyVrWs, PyVrSym	Loads all the symbols in the current workspace, changes the layers and graphic pointers and re-records them.
ChangeText.py	PyVrWs, PyVrText	Loads all the text in the current workspace and changes the text label to the elevation of the entity.
FindLayer12.py	PyVrWs	Counts lines, symbols and text in layer 12 in all open workspaces.
IdLine.py	PyVrLine	Locks onto lines and changes their layer graphic pointer to 5 and their width to 3. The lines will not be resaved, so a replot (Rep) will return the screen to its original state.
IdSym.py	PyVrSym	Locks onto symbols, changes its graphic pointer, adds 20 degrees to their rotation, makes them four times their original size, and redisplays them. The symbols will not be resaved, so a replot (Rep) will return the screen to its original state.
IdText.py	PyVrText	Locks onto text entities, change their text labels to their elevation. The text entities will not be resaved, so a replot (Rep) will return the screen to its original state.
WriteAscii.py	PyVrLine, PyVrSym, PyVrText	Reads all lines, symbols and text in workspace 0 and writes them to a text file.
TextIn.py	PyVrText, PyVrGui	Allows user to import an ASCII text file as VrOne text labels. Displays open file dialog and prompts for coordinate point.
DtmTest.py	PyVrLine, PyVrDtm, PyVrSym	Tests various features of the PyVrDtm class.
TestVrWs	PyVrWs	Tests various capabilities of the PyVrWs class.
TestVrGr	PyVrGr	Tests various capabilities of the PyVrGr class.
TestImgMgr	PyVrImgMgr	Tests various capabilities of the PyVrImgMgr class.

Like any powerful programming language, Python has the ability to modify and damage data. VrOne/Python programming allows modification of the VrOne database and programming errors made by you could damage VrOne files. During development you should back up any VrOne files that will be open during Python program execution!

CARDINAL SYSTEMS, LLC DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL CARDINAL SYSTEMS, LLC BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

If you disagree with the above warning and disclaimer, please do not use Python programming in VrOne.