The Conventions of HOOPS in Python
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:
Define_Callback_Name
Define_Error_Handler
Define_Exit_Handler
Define_Font
Define_Font_By_Reference
PShow_Net_Driver
QSet_Driver
QSet_User_Index
QSet_User_Option_By_Index
QSet_User_Option_By_Index
QShow_Driver
QShow_Net_Driver
QShow_Net_User_Indices
QShow_One_Net_User_Index
QShow_One_User_Index
QShow_User_Indices
Record_Instance_Handle
Report_Error
Set_Driver
Set_User_Index
Set_User_Option_By_Index
Show_Callback_Name
Show_Driver
Show_Font
Show_Net_Driver
Show_Net_User_Indices
Show_One_Net_User_Index
Show_One_User_Index
Show_User_Indices
UnDefine_Error_Handler
UnDefine_Exit_Handler
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 output arguments in C:
int pcount;
int flist_len;
float * plist;
int * flist
HC_Show_Shell_Size(key, &pcount, &flist_length);
plist = (float *)malloc (pcount * 3 * sizeof(float));
flist = (int *)malloc (flist * sizeof(int));
HC_Show_Shell ( key, &pcount, plist, &flist_len, flist);
The Python equivalent would be:
(pcount, flist_len) = HPY.Show_Shell_Size (key)
plist = HPY.ptrcreate ('float', 0.0, pcount * 3)
flist = HPY.ptrcreate ('int', 0, fcount)
HPY.Show_Shell(key, plist, flist)
Note that integer output arguments in HPY.Show_Shell_Size do not need HPY.ptrcreate
and are returned as a Python tuple.
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().
float plist = { 0.1, -6.6, 0.0,
0.1, -0.4, 0.0,
0.4, -0.4, 0.0,
0.4, -0.6, 0.0};
int flist = {4, 0, 1, 2, 3};
key = HC_KInsert_Shell (4, plist, 5, flist);
The Python equivalent would be:
plist = [0.1, -6.6, 0.0,
0.1, -0.4, 0.0,
0.4, -0.4, 0.0,
0.4, -0.6, 0.0]
flist = [4, 0, 1, 2, 3]
key = HPY.KInsert_Shell
(4, HPY.seqToPtr ('float', shell_points), 5, HPY.seqToPtr ('int', face_list))
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:
HC_KEY key = HC_KOpen_Segment("test");
char segpath[256];
HC_Show_Segment(key, segpath);
float i = 0.0f; float j = -0.1f; float k = 0.0f;
int char_count;
HC_Insert_Text(i, j, k, "test");
HC_Show_Text_Count(text_key, &char_count);
can be translated to Python as:
key = HPY.KOpen_Segment('test')
segpath = HPY.Show_Segment(key)
i = 0.0
j = -0.1
k = 0.0
text_key = HPY.KInsert_Text(i,j,k,'test')
char_count = HPY.Show_Text_Count(text_key)
Note that the maximum size of a string is defined in the HOOPS/Python C module,
hpy_wrap.c:
#define MAX_STRING_SIZE 32768
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