The Python Reduced Instruction Set

LightWave 11.6 introduced a new set of Python modules called the Python Reduced Instruction Set, collectively known as PRIS.

PRIS seeks to reduce the complexity of LightWave Python’s direct exposure to the LightWave SDK by providing a collection of functions that encapsulate that complexity for many of the more common actions your plug-in may perform. In addition, this simplication layer has been implemented entirely in Python, a format that affords modification, or extension via additions, on your part should you so choose.

Each PRIS module can be accessed in Python through the existing ‘lwsdk’ module. If you wish to examine or modify any PRIS module, you can find them under the ‘bin/lwsdk/’ package directory of your LightWave 11.6+ installation.

Note

If you are an accomplished LScript developer, you will undoubtedly recognize the design approach of PRIS. A conscious decision was made to model PRIS after the familiar LScript environment to provide a more comfortable transition for some LightWave users between the two languages. Additionally, it allows the PRIS user to leverage existing resources (like the LScript Reference Manual).

Using PRIS

PRIS functionality is fairly straight forward. However, there is a prerequisite to using PRIS, namely that it needs to be initialized before you employ its services. And since it is designed to perform many functions on your behalf, you may need to provide it resources required to accomplish this. For example, to use the PRIS Modeler module, you need to initialize the layer with the ModCommand value that Modeler provides to your Python plug-in.

Note

There are quite a number of ‘unit test’ example PRIS Modeler plug-ins provided with LightWave that illustrate this initialization concept.

Reproduced below is the PRIS Modeler ‘load’ unit test plug-in, using the “single-shot” format (see the “Single-Shot” Exceptions section for more information on this alternative formatting):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
import os

try:
    from lwsdk import ModCommand
    from lwsdk.pris.modeler import Mesh, getdir, load, init, fileexists
except ImportError:
    raise Exception("The LightWave Python module could not be loaded.")

if not init(ModCommand()):
    raise Exception('Failed to initialize PRIS')

content_dir = getdir('Content')
if not fileexists(content_dir):
    raise Exception('A valid content directory is not current set')

object_file = os.path.join(content_dir, 'Objects', 'Animals', 'Cow.lwo')
if not fileexists(object_file):
    raise Exception('Standard LightWave content is not available')

result = load(object_file)
if not isinstance(result, Mesh):
    raise Exception('Load failed: %d' % result)

print 'Successfully loaded "%s"' % result.filename

A Word About Arguments

In some cases in this documentation, you will encounter a notation for arguments that looks like “*args” or “**kwargs”. These are Python notations that bear some brief explanation here.

The first represents a list of arguments in linear order. So, a function defined with this value as an argument:

def my_function(*args):
  pass

when called with any number of parameters (perhaps even none):

my_function(15.0, 'Bob', open('file.txt'))

will have an “args” value that is a Python sequence of objects that corresponds to:

[15.0, 'Bob', <open file 'file.txt', mode 'r' at 0x0000000002150270>]

This argument can appear at any point in an argument list, and will consume the remainder of the arguments that have not already been assigned to values. For example, redefining the function signature thus:

def my_function(distance, *args):
  pass

Would assigned the first argument (15.0) the ‘distance’ parameter, and all remaining parameters will be assigned to the list in ‘args’.

If used, a “**kwargs” parameter must appear that the end of list of arguments, and it contains a Python dictionary that itself contains key/value pairs created when a function is called with one or more keyword assignments:

def my_function(*args, **kwargs):
  pass

my_function(open('file.txt'), distance=15.0, name='Bob')

In the above example, my_function() would contain a single entry in its ‘args’ list for the open file handle, and would have a dictionary in ‘kwargs’ that contained entries for ‘distance’ and ‘name’, with their corresponding values:

{'distance': 15.0, 'name': 'Bob'}

Our use of “*args” in the PRIS modules is intended to replicate the LScript ability to provide variable parameters to a function. The expected values will always be documented, because they will not be obvious from the function’s prototype.

Table Of Contents

Previous topic

Miscellaneous Classes

Next topic

PRIS Common: Common Functionality

This Page