Quick Tutorial

This guide is about installing the developer version of Pyblish, and how to get it up and running with the integration for Autodesk Maya.

Before we start, here's what you'll need:

• Python 2.7
• Git

Installing the core library

Via the command-line, browse to a directory in which you'd like to install Pyblish and run the following command:

$ cd github
$ git clone https://github.com/abstractfactory/pyblish.git

Typically, when installing a Python library it would appear together with your other Python libraries within site-packages.

# For example
c:/Python27/Lib/site-packages/pyblish

But since this is the developer installation of Pyblish, we'll have to expose the library on our own. To do this, append the repository you just downloaded above to your PYTHONPATH environment variable. If you haven't got a PYTHONPATH variable, simply create one.

# For example
$ setx PYTHONPATH=%PYTHONPATH%;c:/github/pyblish

For help with adding environment variables on Windows, see here: http://www.computerhope.com/issues/ch000549.htm

Installing Pyblish for Maya

As before, via the command-line, either stay in the same directory as before, or browse to where you'd like to install the Maya integration and run:

$ git clone https://github.com/abstractfactory/pyblish-maya.git

And again, append this path to your PYTHONPATH as well. In addition, append the inner directory pythonpath as well. This is what will append a file-menu item to your Maya File menu so that you can publish.

# For example
$ setx PYTHONPATH=%PYTHONPATH%;c:/github/pyblish-maya
$ setx PYTHONPATH=%PYTHONPATH%;c:/github/pyblish-maya/pyblish_maya/pythonpath

Testing things out

Congrats! Your developer environment is now complete and we can test things out. When you open up Maya, you'll find two items within your File menu, one which reads "Publish" and one directly below it which reads "Validate". This is how you'll have access to Pyblish from within Maya.

If you aren't seeing the menu-item, something may have gone wrong when adding the environment variables. See Troubleshooting for known issues.

The next step is to run the included test scene. Within Maya, browse to:

c:/github/pyblish-maya/tests/multiple_selection_test/maya

And open up scenes/v001.ma

In the scene, you'll find a low-res character. This is Peter. We'll be publishing Peter, but the first thing you'll need to do is go to your File menu and set your project to:

c:/github/pyblish-maya/tests\multiple_selection_test/maya

And finally, File -> Publish.

Breaking it down

At this point, you should have a published Peter in your project. Have a look at:

c:/github/pyblish-maya/tests/multiple_selection_test/maya/published

It will use the current date and the name of the instance to position the output of your publish. But how does it know to do this? And why does it need to publish onto your project? How can that work with applications that doesn't have a definition of "project" the same way that Maya does?

Well, this is where the power of Pyblish's plugin-architecture comes in.

Everything Pyblish does is broken down into four distinct categories of plugins. You have plugins that select, that validate, extracts and finally conforms. Selectors work by gathering information about your current environment. A Selector is ultimately what defines what it is you are looking to publish. The reason it published Peter in the first place was because there is a plugin running that specifically looks for nodes just like Peter.

Next up is validators. Note that each category of plugins runs in this exact order. A validator looks at the information collected by each selector and validates it. Peter publishes just fine because he is fully valid at the time you open up the scene. But if you were to try and rename one of his node, e.g. Peter_AST -> Peter_AT then one of the validators, the one looking for proper naming convention, would fail and you won't be allowed to publish until he is valid once more.

Extractors do the heavy lifting of actually exporting information from an application. It exports the information previously collected by the selectors. Extractors have a default location at which published content go, this directory is called the "Commit Directory" and is typically located relative your current working file.

# For example, if you are working in a file here
c:/projects/spiderman/my_working_file.ma

# Then published files may end up here
c:/projects/spiderman/published/my_publish.ma

This is because Extractors doesn't know any better. Their sole responsibility is to successfully get information out of an application and onto disk. "Then how do I get files to where I want them?" you may ask.

This is where conformers come in. A conformers job is to take whatever is outputted by extractors and put it where it belongs. It can also do things related to that event, such as notify your co-workers and make an entry in a log somewhere for reference. The process ends with conform and it is with conformers that you integrate your surrounding pipeline with Pyblish.

Next - Making your first Plugin >>>