nuBridge User Manual

Installing nuBridge

Unzip the downloaded zip file

     e.g.: /Users/frank/.nuke/nuBridge_osx64_v1.0.0

Add the resulting path to your NUKE_PATH or use the <HOME_DIR>/.nuke/init.py file to add it, e.g.:

e.g.: nuke.pluginAddPath('/Users/frank/.nuke/nuBridge_osx64_v1.0.0')

After (re)starting Nuke the nuBridge will be accessible via the Help menu, or as a custom pane via the Pane menu.

 

Quickstart

coming soon

Interface

The interface has three main areas:

1. Login Page
2. Main View
3. Details page

Browsing

To browse within the nuBridge, use your nukepedia credentials to log in. You can either use your nukepedia user name or email.

Once logged in you will be presented with the main interface consisting of:

• container buttons (icons along the top bar, representative of the nukepedia catergories as per Downloads dropdown menu)
  
• search & filter bar (along with settings/gear button)
  
• tool list (empty until container button is activated)
  
• drop stack (think of it like a playlist/shopping cart)
  

To start browsing, click one of the container buttons at the top which will pull down the respectative tool-list.

You can use any combination of search, filter & sort options to narrow down the results (for more details, see Searching and Filtering).

Hover over a tool button to see a tool tip with brief information about the tool.
Clicking on the main area of the tool button will take you to the full tool description as per the author's Nukepedia upload. (for more details, see Details Page).

Each tool button also has three sub-buttons which appear when the sursor hovers over it:

Install (see Downloading & Installing) add to stack (same as dragging the tool into the dropstack at bottom) visit website (which will open the respective website).

An orange bar at the top of the tool button indicates that this tool has been downloaded before and exists in the local nuBridge database.

The "update available" decorator in the upper right corner indicates that a new version of the tool was uploaded since the user downloaded this tool.

Note:
This decorator is based on the comparison of time of the download and the online tool's modifcation date. It is not based on version.

So if the user chooses to download an older version instead of the latest version (see Downloading & Installing), the decorator will not show up even when a larger version number is available online. IF the tool author then uploads a new version of the tool, the decorator will show up in the nuBridge.

This behaviour may change based on user feedback.

Details Page

At the top of the details page you will find the same three buttons as the Tool Button buttons offer in the list view:

1. Install (see Downloading & Installing)
2. add to stack (same as dragging the tool into the dropstack at bottom)
3. visit website (which will open the respective website).

Along with some tool statistics, you will also find the same html page that you can find on nukepedia.com.

The drop stack remains active in this view should you wish to add the current tool to it from here.

The back button will take you back to the main list view (HotKey = backspace).

Searching and Filtering

Directly below the top row of Container Buttons you will find the search & filter area.

In order to activate these features, you must first pull down a container.

show:

The tool types available in the "show" menu for each container correspond to the tool types you will already be familiar with on Nukepedia.

Therefore the containers – gizmos, plugins, toolsets & blink – have tool types which correspond to Nuke's Node menu, eg: 3d, channel, colour, deep, etc.

The Python container has these types – 3d, flipbook, imports/export, misc, nodegraph, render & ui.

The Presets and Misc containers have no specific types.

The Hiero container has python & softeffects types.

The All container shows the content of all containers, and therefore has no specific types.

All containers share the meta types – all, available updates & installed – to further assist finding tools & knowing which tools you already have installed.

sort by:

The tool pages can be sorted by – catergory, date, download count, name & author.

The arrow button to the right of the sorting menu toggles the sort order. Toggling will invert the list order ie. A-z, z-a.
Example: If pulling down the All container and sorting by download you can quickly find the most/least downloaded tool.

search box:

The search box enables you to further refine the current visible list of tools by filtering by a specific author or tool name.
This field is dynamic so it will adjust the results as you type.

Drop Stack

The Dropstack serves as a type of favourites list/shopping cart to enable you to bulk download tools.

Tools can be added by either of these three methods:

1. Drag & Drop: literally drag & drop a tool item from the list menu.
2. Click the "add to stack" button on the relevant tool button.
3. Click the "add to stack" at the top of the Tool Detail view.

When there is at least one tool in the Drop Stack, the "Install" button becomes active.

The Drop Stack menu on the left, enables you to save & load your "favourite" tool lists.
These lists are saved to your online Nukepedia account. There is no limit to the amount of lists you can save. You can also export a favourites list to text file, so it can be shared via email/chat/etc.

Example:

As a freelancer this enables you quickly download your favourites no matter which company you are working at this week. Additionally you can export your favourites list to share with colleagues, eg sharing a default tool collection for a show in a decentralised setup.

The three buttons to the left of the Drop Stack, are load, save & clear:

• Load will automatically display all previously saved lists for your account and permit importing a new list from a file.
• Save allows you to save a new list, overwrite an existing list or export the current list as a text file.
• Clear will clear the stack.

Downloading & installing

There are three ways to download a tools:

1. Install button on the main tool button (if you are in a rush):
   
2. Install button on Details Page (if you want to read up on details first):
   
3. Install button under Drop Stack (to bulk download lists of tools)
   

The downloaded files are placed in the repository location defined in the settings (default: <HOME>/Nukepedia).

I.e. <HOME>/Nukepedia/downloads (if the folder does not exists it will be created).
Each tool will have it's own sub folder consisting of the tool name and it's unique ID.
Inside the tool folder you there will be one sub folder per tool version, so previously downloaded tools aren't overwritten.

The location of the Nukepedia repository is also customisable as of v0.2.0 by setting the environment variable NKPD_REPO_PATH

Inside the repository folder you will also find the NukepediaDB.sqlite.
This is a lightweight and self contained database to keep track of downloaded and installed tools. The contents of this database drive the resulting nuBridge menu and enable the nuBridge to mark tools as downloaded as well as inform the user of available updates for already downloaded tools.

It is also required for handling local tools via the "Installed Tools" view in the settings dialog. For those who wish to examine this file further, there are lots of free sql browser apps available.

Currently only zingle gizmo files will be automatically installed and show up in the Nukepedia menu. Due to the state of Nuke's plugin envionrment (aka Wild West of program extensions) there is no standardised way to package up extensions such as gizmos, plugins, python scripts etc, so the auto installer can only operate on simple cases.

Hopefully we can define a "nuke packaging standard" at some stage which will enable the installer to be much more effective.

There are a couple of ways to cusomtise and extend the installer, for details see Customisation

 

Settings

The settings dialog can be accesses before logging in via the "Settings" button or after logging in via the gear menu in the upper right (next to the search and filtering options).

There are currently three tabs:

1. Installed Tools
   This tab shows you which tools have been downloaded before along with some info about their local path and version.
   Local tools can be managed via a right click menu.
   If the tool could not be installed automatically, the "localPath" field will be empty.
2. Options
   This tab shows various options to cusomtiase the nuBridge's behaviour
3. Network
   This tab is reserved for dealing with proxy server settings. The UI is not yet implemented but nuBridge can operate fmor behind a proxy server if the environment variable HTTP_PROXY is set. See Environment Variables

The settings file is written to <HOME>.config/Nukepedia/nuBridge/settings.ini

Environment Variables

Some settings can be driven by environment variables to enable a more pipeline friendly setup. If an environment variable is set the respective UI setting will be disabled to avoid ambiguity and keep users from accidentally changing facility or show settings:

• NKPD_LOG_LEVEL
  This can be set to any of the following values (not case sensitive): critical, error, warning, info, debug
• NKPD_REPO_PATH
  This can be set to point to a directory for the nuBridge to use as the repository for reading and writing. This enables a shared repository setup based on shot environment and should enable facilities to integrate nuBridge into their pipeline.
• NKPD_DOWNLOAD_ONLY
  This can be set to any value to suppress nuBridge's installer from trying to proces any downloaded files itself.
  In combination with the custom post-download function this enables facilities to take control over what happens with the downloaded file to avoid artists messing with setup that utilises a shared repository for production work.
  e.g. a psimple python script could be written and registered to copy downloaded files to a quarantine area for assessment, approval, testing, backup, etc.
• NKPD_BAKE_GIZMOS
  This can be set to drive the behaviour for when gizmos are created. Valid values correspond to the "bake gizmos" setting found in the options tab:
  0 - let the "Installed Tool Table" dictate the behaviour on a per tool basis (i.e. no global override)
  1 - always bake gizmos to groups when they are created, regardless of their setting in the "Installed Tools" table
  2 - never bake gizmos to groups when they are created, regardless of their setting in the "Installed Tools" table
• HTTP_PROXY
  Use this environment variable to enable nuBridge from behind a web proxy server. You can set the this environment variable via your init.py or menu.py, e.g.:
  import os
  os.environ['HTTP_PROXY'] = 'http://proxy_user:proxy_pwd@<proxy_server_ip>:<proxy_server_port>'

Customisation (experimental)

Example 1   -   register post download function

This is the simplest way to take over once a file has been downloaded. Simply write a funciotn that takes one argument representing the tool item and register the funciton as a post download process.

The toolItem will have all sorts of info that will enable you deal with the file yourself, e.g. copy to a backup or approval area.

def myFunc(toolItem):
    nuke.tprint('custom process after download')
    nuke.tprint(dir(toolItem))

Nukepedia.registerPostDownloadProcess(myFunc)

Example 2   -   subclass ProcessorBase

Subclassing from from controller.Processor.ProcessorBase and re-implementing the process() method will enable you to customise how the nuBridge installs tools to the local database and thus how the Nukepedia tool menu is created.

In v0.1.2 you need to import from the controller package like this:
   from controller.Processor import ProcessorBase

In future versions you wil be able to improt from the Nukepedia module, e.g.:
   from Nukepedia import ProcessorBase

The following example is taken from nuBridge_osx64_v0.1.2/src/controller/Processor.py (NEEDS UPDATE)

class Processor(ProcessorBase):

    def __init__(self, parent=None):
        super(Processor, self).__init__(parent)

    def copyFilesToPluginPath(self, downloadPath):
        '''
         Copies the processed files to the plugin path where Nuke can pick them up
        '''
        self.createInstallDir()
        LOGGER.debug('copying {0} to {1}'.format(downloadPath, self.pluginPath))
        # sanitise gizmo name so there are no dots in it (Nuke spits the dummy otherwise)
        baseName, ext = os.path.splitext(os.path.basename(downloadPath))
        fileName = baseName.replace('.', '_') + ext
        filePath = os.path.join(self.pluginPath, fileName)
        shutil.copy2(downloadPath, filePath)
        return filePath

    def createInstallDir(self):
        '''
        Return the full directory the respective tool is meant to be copied to.
        If the directory doesn't exist, create it here.
        '''
        self.pluginPath = os.path.join(common.NKPD_FILE_ROOT_PATH,
                                       self.toolItem.toolType,
                                      '{}_{}'.format(self.toolItem.title, self.toolItem.id_),
                                      self.toolItem.version)
        if not os.path.isdir(self.pluginPath):
            os.makedirs(self.pluginPath)

    def process(self):
        '''
        Process downloaded file (e.g. file could be a zip file) and emit signals to inform nuBridge
        of the new plugin pathas well as extracted files (in case we need to keep track of them for
        later uninstallation.
        The default processor should do nothing (for files that can be copied directly to the plugin
        path to be useful).
        '''
        fileExt = os.path.splitext(self.toolItem.fileName)[-1]
        dlPath = self.toolItem.downloadInfo['downloadPath']
        newFiles = []
        if fileExt == '.gizmo':
            # gizmo files only need to be copied to the plugin path, so no more porcessing required
            LOGGER.debug('processing (copying) {0}'.format(dlPath))
            filePath = self.copyFilesToPluginPath(dlPath)
            newFiles.append(filePath)
            print filePath
            pluginPath = os.path.dirname(filePath)
            print pluginPath

            # register new file paths so the uninstaller can do it's job properly
            # this may not be needed as we currently assume everythign lives
            # inside the new plugin path
            # so removing that and the respective DB entries should qualify as "uninstall" for now
            self.registerFilePaths(newFiles)

            # register the plugin path that should be added to load this tool
            self.registerNewPluginPath(pluginPath)

            # register info to create the new menu item (if needed)
            # for gizmos we can just use the file name without the extension to use as the command
            nodeClass = os.path.splitext(os.path.basename(filePath))[0]

            # create the command to be executed from the menu to run this tool
            menuCommand = "nuke.createNode('{}')".format(nodeClass)

            # register it to create teh UI part
            self.registerNewMenu(command=menuCommand)

        else:
            # raise IOError if processor cannot properly deal with the downloaded file
            # this will trigger an info message for the user to install the file manually
            raise IOError

Nukepedia.setProcessor(MyProcessor)