VrOne/Python Programming
|
ON-LINE REFERENCE DOCUMENTATION CARDINAL SYSTEMS, LLC 386-439-2525 www.cardinalsystems.net |
Python is an object-oriented scripting language. Its design mixes software engineering features of traditional languages with the usability of scripting languages. It is possible to write Python scripts that interface with VrOne thru VrOne/Python classes. This interface allows full access to reading and writing the VrOne database and the access to interactive editing. 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. You 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 the 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, along with 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 in 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, you can get the entire system for free over the Internet. You may use Python for other programming tasks other than VrOne.
You should have prior programming experience with Python or other languages such as C, C++, Pascal, BASIC or Java. This is not an absolute requirement but you 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 your local bookstore such as Barnes and Noble or on-line at 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 the “Require PY command to run Python scripts” is turned off, then you can type just the name of the python script to run it, assuming there is not a built-in command, function key, or macro with 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 when running python scripts 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. If there is an error during the execution of a script it is displayed in this window. During development this window should be left partially visible so output can be seen.
Python scripts may be started from the following areas:
Python classes have been developed to facilitate the interfacing and communication between a Python script and VrOne. These classes are:
|
Manages VrOne file (workspace) queries and some file operations. |
|
|
Holds and manipulates VrOne line data including loading lines from a file. |
|
|
Holds and manipulates VrOne symbol data including loading symbols from a file. |
|
|
Holds and manipulates VrOne text label data including loading text labels from a file. |
|
|
Coordinate geometry routines |
|
|
Graphical user interface and miscellaneous system routines |
|
|
DTM routines |
|
|
DTM Surface Management routines |
|
|
Graphics routines for drawing directly to graphics windows, and querying cursor state. |
|
|
Layer management routines |
|
|
Allows various VrOne configuration parameters to be viewed and changed. |
|
|
Displays standard menu keys dialog. |
|
|
Creates a dialog box with programmable entry fields (prompts) to allow entry of parameters. |
|
|
Provides a way to write true event-driven python scripts
that have the look and feel of a standard VrOne application. |
|
|
Image management routines. |
The following examples are provided and 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 |
|
PyVrSym, PyVrLine |
Loads the last symbol and draws a star type line around the symbol. |
|
|
PyVrLine, PyVrSym |
Load the last line and adds symbols to line ends. |
|
|
PyVrWs, PyVrLine |
Loads all the lines in current workspace, change the layers and graphic pointers and re-records them. |
|
|
PyVrWs, PyVrSym |
Loads all the symbols in the current workspace, change the layers and graphic pointers and re-record them. |
|
|
PyVrWs, PyVrText |
Loads all the text in the current workspace, changes the text label to the elevation of the entity. |
|
|
PyVrWs |
Count lines, symbols and text in layer 12 in all open workspaces. |
|
|
PyVrLine |
Lock onto lines; change 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. |
|
|
PyVrSym |
Lock onto symbols, change its graphic pointer, add 20 degrees to its rotation, make it four times it's original size and redisplay it. The symbols will not be resaved so a replot (Rep) will return the screen to its original state. |
|
|
PyVrText |
Lock 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. |
|
|
PyVrLine, PyVrSym, PyVrText |
Reads all lines, symbols and text in workspace 0 and writes them to a text file. |
|
|
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 |
Test various capabilities of the PyVrWs class. |
|
TestVrGr |
PyVrGr |
Test various capabilities of the PyVrGr class. |
|
TestImgMgr |
PyVrImgMgr |
Test 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.