The Tech Artist

Musings

Attaching Scripts to Objects in Panda3D – Part II

by on May.06, 2012, under Musings, Panda3D, Panda3D Scene Editor

In my last post I showed how to attach a Python object to a node path in order to create a ‘hook’ in the Panda3D scene graph. In this post I’ll be showing how to dynamically add additional code to that object at runtime. Attaching code to objects in this way will be at the core of offering drag and drop scripting functionality in the same manner as Unity.

Once we have the PandaObject the next thing we could do is to subclass it in order to add additional code. Since I’m building an editor I want to offer the user an easy way to add, remove and combine different scripts for a node path, so in this case we’ll use the PandaObject as a hook only and then ‘hang’ other scripts from it.

In the context of our editor, the user will presented with a file browser displaying all the scripts in their project. This hierarchy will be representative of the directory structure on disk, and the user should be able to drag and drop any script onto any node in the scene. This presents an interesting problem as essentially we need to be able to instantiate a class from a file path the user selects at runtime. Thankfully python’s imp module offers some very handy tools for solving this kind of problem.

So now our PandaObject code looks like this:

import os
import sys
import imp

from direct.showbase.DirectObject import DirectObject

class PandaObject( object ):

    def __init__( self, np ):

        # Store the node path with a reference to this class attached to it
        self.np = np
        self.np.setPythonTag( 'PandaObject', self )

        self.instances = {}

    @staticmethod
    def Get( np ):

        # Return the panda object for the supplied node path
        return np.getPythonTag( 'PandaObject' )

    @staticmethod
    def Break( np ):

        # Detach each script from the object
        pObj = PandaObject.Get( np )
        if pObj is not None:
            for clsName in pObj.instances.keys():
                pObj.DetachScript( clsName )

        # Clear the panda object tag to allow for proper garbage collection
        np.clearPythonTag( 'PandaObject' )

    def AttachScript( self, filePath ):

        # If the script path is not absolute then we'll need to search for it.
        # imp.find_module won't take file paths so create a list of search
        # paths by joining the head of the script path to each path in sys.path.
        head, tail = os.path.split( filePath )
        if not os.path.isabs( filePath ):
            srchPaths = []
            for sysPath in sys.path:
                srchPaths.append( os.path.join( sysPath, head ) )
        else:
            srchPaths = [head]

        # Import the module. Pass imp.find_module the name of the module
        # and a list of paths to search for it on.
        name = os.path.splitext( tail )[0]
        modDetails = imp.find_module( name, srchPaths )
        mod = imp.load_module( name, *modDetails )

        # Get the class matching the name of the file, attach it to
        # the object
        clsName = name[0].upper() + name[1:]
        cls = getattr( mod, clsName )

        # Save the instance by the class name
        self.instances[clsName] = cls( self.np )

    def DetachScript( self, clsName ):

        # Remove an instance from the instance dictionary by its class name.
        # Make sure to call ignoreAll() on all instances attached to this
        # object which inherit from DirectObject or else they won't be
        # deleted properly.
        if clsName in self.instances:
            instance = self.instances[clsName]
            if isinstance( instance, DirectObject ):
                instance.ignoreAll()
            del self.instances[clsName]

Note the two new methods, AttachScript() and DetachScript(). We will use these to add and remove additional code to our PandaObject. Code to be added will be its own class which I will refer to from here as a ‘behaviour’.

Behaviours are attached using the AttachScript method which takes a path to a python script as an argument. By using Python’s imp module we can import a module using a string, and it doesn’t have to be found on sys.path either. There is one caveat though – imp.find_module will only take a file name as its first argument, absolute or relative paths will not work. As I want this to handle relative paths I have to build a list of search paths to pass to find_module by joining the directory of the script to each of the sys.paths.

There is another restriction in that the name of the behaviour’s class must be named an uppercase leading match of the file that it lives in. While this goes against my ideas of dictating how the developer approaches their project, I don’t think it’s too restrictive and also matches the Python / Unity paradigm of naming classes in accordance to the files they live in.

Once we have found the class name we create an instance of it with the PandaObject’s node path as an argument. Any behaviour we add is probably going to modify the node path in some way, so we’ll need to pass this through. All instances are then stored in the PandaObject’s instances dictionary – something I’ll probably end up changing as currently it is not possible to attach more than one of the same type (named) of behaviour to a PandaObject.

We can remove instances that are attached to our PandaObject by passing the class name to DetachScript(). I’ve added a call to ignoreAll() for any behaviours that are inherited from DirectObject as they won’t be garbage collected without removing their reference from the messenger first.

Now to create some kind of basic behaviour. The following code will move the node path slowly up and down when started:

import math

from direct.showbase.DirectObject import DirectObject

class NewBehaviour( DirectObject ):

    def __init__( self, np ):

        # Set the node path this behaviour will control then bind Start and
        # Stop events.
        self.np = np
        self.accept( 'StartNewBehaviour', self.Start )
        self.accept( 'StopNewBehaviour', self.Stop )

    def Update( self, task ):

        # This will move the node path up and down like a sine wave.
        self.np.setZ( self.initZ + math.cos( task.time ) )

        # Keep this task running so long as the node path is valid.
        if not self.np.isEmpty():
           return task.cont

    def Start( self ):

        # Get our initial z position then add an update task to be processed
        # every frame.
        self.initZ = self.np.getZ()
        self._task = taskMgr.add( self.Update, 'UpdateTask' )

    def Stop( self ):

        # Remove the update task from the task manager. Remember to set the
        # _task member to None or else the behaviour won't be garbage
        # collected!
        taskMgr.remove( self._task )
        self._task = None

Nothing too special going on here. We store the input node path and bind some events when the class is instantiated, and there’s some basic wrapping of the task manager going on there too.

Now to bring the whole thing together. We start by loading the default box model, parenting it under render and attaching a PandaObject. We then pull that object back out of the scene graph in a different scope and attach the behaviour to it by passing the file path to the script:

import direct.directbase.DirectStart

from pandaObject import PandaObject

def Foo():

    # Load a model, put it in the scene graph and attach a PandaObject hook to
    # it
    box = loader.loadModel( 'box' )
    box.reparentTo( render )
    PandaObject( box )

def Bar():

    # Pull the node path out of the scene graph and attach the new behaviour
    # to it. myNp could be obtained other ways; returned from a collision
    # picking event for example.
    myNp = render.find( '*box*' )
    pObj = PandaObject.Get( myNp )
    pObj.AttachScript( 'newBehaviour.py' )

Foo()
Bar()

# Move the camera so we can see the box, then send the message to start the
# new behaviour.
base.cam.setY( -10 )
messenger.send( 'StartNewBehaviour' )

run()

Running the above code should show a box that floats up and down. To remove the node cleanly we have to make sure we stop the task running first, then we can remove it like normal:

messenger.send( 'StopNewBehaviour' )
myNp = render.find( '*box*' )
PandaObject.Break( myNp )
myNp.removeNode()

So while this seems overly complex in order to get a box to move, you can imagine how neat this works when attached to a script file browser. By binding some drag and drop events we can easily attach the user’s script to any node path in the scene.

2 Comments more...

Attaching Scripts to Objects in Panda3D – Part I

by on Jan.05, 2012, under Musings, Panda3D, Panda3D Scene Editor

Now that I have a basic scene editor capable of adding, transforming and editing the properties of nodes, the next thing to do is to get some scripted behaviour happening. Having used Unity for my last project I’ve found my design choices to be greatly influenced by this tool, and Unity takes the intuitive approach of allowing the user to attach scripts to nodes in the scene hierarchy. Any subsequent manipulation of the node or its components by these scripts can be done using reserved keywords in the body of the script.

This idea of packaging code close to the node path it’s responsible for seems very object oriented and appeals greatly to me, and there’s no reason why we can’t do a similar thing in Panda3D. The most logical choice is to start subclassing NodePath or PandaNode, and adding the additional behaviour and methods there. Consider the following code:

import direct.directbase.DirectStart
from panda3d.core import NodePath

class MyNodePath( NodePath ):

    def DoSomething( self ):
        print 'Hello world!'

def Foo():

    # Create an instance of our custom node path, stick it into the scene graph
    myNp = MyNodePath( 'myNodePath' )
    myNp.reparentTo( render )
    myNp.DoSomething()

def Bar():

    # We're in a different scope and have lost the original reference to myNp,
    # so we need to pull it out of the scene graph again
    myNp = render.find( 'myNodePath' )
    myNp.DoSomething()

Foo()
Bar()

run()

However when we run this we get:

Hello world!
Traceback (most recent call last):
  File "test.py", line 24, in
    Bar()
  File "test.py", line 21, in Bar
    myNp.DoSomething()
AttributeError: 'libpanda.NodePath' object has no attribute 'DoSomething'

That’s odd – our method seems to have disappeared. Perhaps this is to be expected however, as a NodePath class is meant to serve as a path to a node – not a node itself. Maybe a reference to a node is just a wrapper generated during runtime. Let’s try a more concrete example by subclassing the PandaNode directly:

import direct.directbase.DirectStart
from panda3d.core import PandaNode

class MyPandaNode( PandaNode ):

    def DoSomething( self ):
        print 'Hello world!'

def Foo():

    # Create an instance of our custom node
    myPNode = MyPandaNode( 'myPandaNode' )
    myPNode.DoSomething()
    render.attachNewNode( myPNode )

def Bar():

    # We're in a different scope and have lost the original reference to myNp,
    # so we need to pull it out of the scene graph again
    myNp = render.find( 'myPandaNode' )
    myNp.node().DoSomething()

Foo()
Bar()

run()

This doesn’t seem to work as expected either:

Hello world!
Traceback (most recent call last):
  File "test.py", line 24, in
    Bar()
  File "test.py", line 21, in Bar
    myNp.node().DoSomething()
AttributeError: 'libpanda.PandaNode' object has no attribute 'DoSomething'

So what the Sam Hill is going on here?  I created an instance of MyPandaNode, stuck it in the scene graph but can’t access its method once I’ve pulled it back out again. This seems like an odd limitation and one that on searching the Panda3D forums seems to bite everyone sooner or later. It happens because Panda is essentially a C++ engine under the hood, and whenever you perform a query that returns a PandaNode or NodePath you are handed the C++ object with a thin Python wrapper around it. Unless you keep track of your custom NodePaths and never lose references to them you’ll always get a newly minted, default Python wrapper returned. Subclassing in Python merely subclasses the wrapper class, not the C++ class.

This makes our quest to attach code to object a lot more difficult, but there should still be a straightforward solution. If we can’t subclass NodePath, then surely we should be able to wrap it. This works fine but we need to get back our custom class once we have the NodePath. Thankfully NodePath has a great little method which can be used to attach a python object to a NodePath, this will stay attached even if we lose the initial reference to the NodePath and have to pull it out of the scene graph again. It’s called ‘setPythonTag’ and can be used to back reference the NodePath to your custom class:

class MyObject( object ):

    def __init__( self, name ):
        self.np = NodePath( name )
        self.np.setPythonTag( 'base', self )

Now whenever we have a NodePath we can simply get back to our custom class by calling:

myNp.getPythonTag( 'base' )

Neat – we’ve essentially solved our problem! Yes, but we’re also introduced a new one. Consider the following:

import direct.directbase.DirectStart
from panda3d.core import NodePath

class MyObject( object ):

    def __init__( self, name ):
        self.np = NodePath( name )
        self.np.setPythonTag( 'base', self )

    def __del__( self ):
        print 'deleted!'

    def DoSomething( self ):
        print 'Hello world!'

def Foo():

    # Create an instance of our custom class, stick the node path into the scene
    # graph
    myObj = MyObject( 'myNodePath' )
    myObj.np.reparentTo( render )
    myObj.DoSomething()

def Bar():

    # We're in a different scope and have lost the original reference to myNp,
    # so we need to pull it out of the scene graph again
    myNp = render.find( 'myNodePath' )
    myNp.getPythonTag( 'base' ).DoSomething()

    # Try to remove the node from the scene graph, we should see the deleted
    # message from the destructor
    #myNp.clearPythonTag( 'base' )      # Uncommenting this line will result in the node path being destroyed properly
    myNp.removeNode()

Foo()
Bar()

run()

You can see from running the above script that you will never see the ‘deleted!’ message printed from the destructor, unless the python tag is cleared first. This is because essentially we’ve created a circular reference: The class contains a reference to the NodePath, which contains a reference back to the class as a Python tag. While this isn’t a huge problem if we remember to break the reference, it can cause memory leaks if not dealt with properly. If you detach a NodePath from the scene graph expecting it to be deleted and lose track of your instance of MyObject the two will never be garbage collected – and neither will you be able to access either of them to break the reference.

Can Weakref Help?

In short: no. At least, not obviously. I made the mistake of thinking that the problem could be solved by making the back reference a weak reference, which meant that Python’s garbage collection would properly destroy the NodePath once all other references had been removed. For example:

self.np.setPythonTag( 'base', weakref.proxy( self ) )

Unfortuantely you need to have at least one non-weak reference to an object or it will be removed as soon as you drop out of the scope in which it was created, leaving us back with the intial problem. Using weakref doesn’t look like it will be a magic bullet, you would have to use it in conjunction with another solution…

Other Potential Solutions

It would be possible to keep track of each node path’s custom object using a dictionary as part of a manager class, but I think you would eventually come up against the same problem. In order to remove a node path from the scene graph properly you would need to make sure you removed it from the dictionary in the manager object as well.

I considered other wacky solutions like storing values and functions as individual python tags on a node path, but you would need a manager class which knew how to access and run the code. In short, I don’t think it would be a very elegant solution.

So What is the Solution?

At the moment I’m leaning more to the circular reference idea, and adding an additional Break() method to break the circle and allow garbage to be collected normally. I’ve also opted to go with a static method to retrieve the PandaObject from the NodePath, as this keeps things nice and neat; another developer doesn’t have to know the name of the tag this class is hidden in either, so it looks rather clean:

class PandaObject( object ):

    def __init__( self, np ):

        # Store the node path with a reference to this class attached to it
        self.np = np
        self.np.setPythonTag( 'PandaObject', self )

    @staticmethod
    def Get( np ):

        # Return the panda object for the supplied node path
        return np.getPythonTag( 'PandaObject' )

    @staticmethod
    def Break( np ):

        # Clear the panda object tag to allow for proper garbage collection
        np.clearPythonTag( 'PandaObject' )

    def DoSomething( self ):
        print 'Hello world!'

This means calling custom methods on our NodePath will look something like this:

pObj = PandaObject.Get( render.find( 'myNodePath' ) )
pObj.DoSomething()

If we want to completely remove a node, we have to remember to call Break() before detaching it to make sure the circular reference is broken.

In summary, setPythonTag() is your friend. Just make sure to break any circular references you create or otherwise your NodePaths won’t be collected as you might expect. In my next post I’ll show some other creative uses for the technique described above.

3 Comments more...

Site Update

by on Sep.05, 2011, under Musings

As much as the default WordPress theme appeals due to its simplicity, it did strike me as a bit boring after a while. After browsing some of the themes available I finally decided to use Pixel, which caught my eye due to its colour scheme and clean look. Unfortunately after installing I found some of the buttons to be in the wrong place, the sidebar too wide and the RSS button looked ghastly and didn’t seem to fit with the rest of the theme. Thankfully WordPress allows you to edit the theme code directly, and I fixed these issues with a little tinkering.

Aside from the new look I’ve reorganised some of the content. The art gallery is now split into three sections: 2D, 3D and the environment work I did for the video game, LA Noire. I’ve also added a code section which I’ll hopefully be adding to more over the next couple of days.

Hope you enjoy!

1 Comment more...

…and so it begins

by on Aug.06, 2011, under Musings

After years of having no internet presence aside from the usual social networks, I’ve finally decided to join the ranks of those who possess Mighty Internet Publishing Power™ and do my bit to make the web a more crowded place.

In addition to making posts largely made up of incoherent babble, I’m hoping to publish parts of my portfolio, art and code. So sit back, relax and join me – if you will – while I blunder my way through 3D territory.

1 Comment more...

Looking for something?

Use the form below to search the site:

Still not finding what you're looking for? Drop a comment on a post or contact us so we can take care of it!