The Conventions of HOOPS in Python


Linking with the HOOPS Python Bindings

Python Defines

Routine Names

HOOPS Routines Available in Python

Differences Between Using HOOPS with Python and with C

Datatypes Names and Language Declarations

Stand-Alone Example Programs


Linking with the HOOPS Python Bindings

Python applications must link to the HOOPS Python object

HPY.py (Windows)
located in the [installation]/lib directory and

HPY.py (Unix/Linux)
located in the [installation]/lib/[platform] directory.
Applications can also link to the HOOPS/Stream Python module, HTK.py, for HSF output. These Python modules require the HOOPS/Python modules hpy_wrap.c and htk_wrap.cpp to be compiled into a Windows dll or a Unix shared library, and this can be done using the supplied VC++ project or makefile, respectively.


Python Defines

To have access to function prototypes for the routines that comprise the HOOPS API, Python users must use the following line:
To have access to the HOOPS/Stream functions Write_Stream_File and Read_Stream_File,Python users must use the following line:

Routine Names

Prefixes

Each routine name, such as Insert_Polyline , in your HOOPS program must have a prefix before the name will actually be usable on your computer system. The prefix varies depending on which language you're calling from, and sometimes depending on the brand of the language you're calling from. When calling from Python, all calls to the HOOPS/3dGS API are made through the HPY interface, such as:

Common Names

All HOOPS routine names follow a standard pattern: the first part of the name is an active verb indicating what's to be done, and the second part is a descriptive noun.
The most common verbs are
Define Changes a global system status, or adds something to a system-wide table.
Insert Incorporates a new picture element into the current segment and into the scene.
KInsert Incorporates a new picture element and returns a reference key to the element.
QInsert Quickly opens a different segment.  Inserts a new picture element and closes the segment
DInsert Double precision version of insert.  Pass doubles instead of floats.
Edit Changes the definition of an existing picture element.
DEdit Double precision version of edit.  Pass doubles instead of floats.
Set Loads an explicit new value for an attribute.
QSet Quickly opens a different segment. Sets and closes the segment.
UnSet Undoes a Set. (Allows an attribute value to be inherited once again from a higher level.)
QUnSet Quickly opens a different segment. UnSets and closes the segment.
Show Retrieves an item of information from the system.
DShow Double precision version of show.  Returns doubles instead of floats.
Begin Initializes a database information search.
Find Steps an information search along.
End Completes an information search.
(Please note that there are a number of miscellaneous verbs that arise from the various state-modifying routines, such as Dolly_Camera and Rename_Segment . These less frequently occurring verbs are usually self explanatory.)
The most common nouns include the following:
Segment The routine works with a graphics segment (a place for storing picture elements) as one element.
Camera The routine positions or moves the viewing camera.
Object The routine works with the "real" objects (as organized into segments) from which your scene is composed.
Text The routine affects the text labels appearing in the scene.
Return to Top

HOOPS Routines Available in Python

Most functions available under C are available in Python except for:
Return to Top

Differences Between Using HOOPS with Python and C

Functions

Calling the HOOPS Python interface is exactly like calling the C interface. All of the functions in C that require HC_[function] require HPY.[function] in Python.

Pointers and write-back values

The largest difference between using HOOPS with Python and C is found when passing array pointers as either input arguments or output arguments ('write-back' values), i.e. you pass a pointer to a function and it writes back values to that location. The HOOPS Python interface provides pointer and write-back functionality for vector arrays by using helper functions. Note that write-back values are returned as Python tuples, and therefore should not be included in the argument list.
The following example uses Show_Shell to demonstrate the proper use of output argument vectors in Python. For contrast, the C method is shown with the corresponding Python method, which uses the helper function HPY.ptrcreate():
For input argument vectors, Python programmers must use the helper function HPY.seqToPtr(), which creates a C pointer from a Python list or other sequence. Again, the following example contrasts the differences between C and Python for the function Insert_Shell().

Other Data Types

In all other cases, the HOOPS data types map directly between Python and HOOPS. The HOOPS/Python C module takes care of all pointer creation for pointer types other than arrays, so helper functions are not needed when a function's output arguments are strings or pointers to single-values. Therefore the C version of Show_Segment and Show_Text_Count:
can be translated to Python as:
Note that the maximum size of a string is defined in the HOOPS/Python C module, hpy_wrap.c:
This can be changed as needed.
Return to Top

Datatype Names and Language Declarations in Python

The Python datatypes translate as follows:
HOOPS HOOPS (HC) type Python type
'string' char* string
'writes string' const char * string
'HC_KEY' HC_KEY long
'int' int int
'writes int' &int int *OUTPUT
'float' float float
'writes float' &float float *OUTPUT
'point' floats[3] HPY.seqToPtr ('float', floats)
'writes point' &floats HPY.ptrcreate ('float', 0.0, 3)
'ints' ints[x] HPY.seqToPtr ('int', ints)
'writes ints' &ints HPY.ptrcreate ('int', 0, x)

 
Return to Top

Stand-Alone Example Programs in Python

A simple, stand-alone HOOPS Python program--pytest.py--can be found in the [installation]/demo/common/Python/ directory. The program demonstrates the usage of a select number HOOPS/3dGS routines as called from the HPY interface, and is useful in understanding the basic syntax of the API as well as for test purposes.
Return to Top