Houdini 13.0 Nodes

interface version 1

Sets environment variables defined in environment scripts and loads OTLs accordingly.

Introduction

The Environment qL operator provides a simple but powerful method to set up environment variables for your scenes. It also provides a flexible way to load the assets needed by your scene.

The operator runs python scripts (called env scripts). It looks for such scripts by starting at current hip file directory, then traveling upwards in the folder hierarchy.

The whole point of the Environment qL operator is to provide an easy way to define your environment in a hierarchical and/or programmatic way. For example you can define site defaults in a site envrionment script, which can be overridden at the job level, which can be overriden again at the scene and/or at the shot level.

The operator even provides you the opportunity to override parameters on the asset interface (temporarily or permanently).

Moreover, since the env scripts are actually written in python, you can do whatever you can do with python: process file paths, run other scripts, create files or directories, or even connect to a database, etc.

Building the Environment

1.

First the operator builds a list of environment scripts by looking for files matching the pattern specified in the Env File Pattern parameter. It starts in your $HIP directory and then it travels up to its parent directories up to the root of the filesystem.

Tip

You can have directory names in the Env File Pattern parameter like '.env/*.py' if you prefer to put the environment scripts in a subdirectory.

2.

Next, the scripts are run in a top-down order (script(s) closest to the file system hierarchy root are run first – script(s) in the $HIP folder are run last.)

If a site environment script is specified in the Site Env File parameter, it will always be the first to be run.

Tip

All the scripts are executed in the same local namespace, so variables and other objects (i.e. functions and classes) defined at 'higher' level scripts can be referenced and reassigned in 'lower' level ones. (Almost like if it was one single script.)

3.

Finally, script-defined variables with ALL UPPERCASE names get exported to the Houdini environment and also listed in the Variables tab in the parameter interface.

(The env building method is designed to be application-independent, so the same env scripts could be used from other apps with a Pyton API.)

Env Script Variables

The following variables are available in all environment scripts:

HIP

Path of the current scene file. (Usually the same as the $HIP environment variable.)

HIPNAME

The name of the Houdini scene.

JOB

Value of the $JOB environment variable.

ENV_SCRIPT_PATH

Path of the current env script.

ENV_SCRIPT_NAME

Name of the current env script.

ENV_SCRIPTS

A dictionary of the scanned environment scripts in which the key is the name of the script while the value is the path to that script. While ENV_SCRIPT_PATH and ENV_SCRIPT_NAME is only available at the moment when the given script is running, this dictionary is available in the first env script that gets executed. So for example you can put the line 

JOB=ENV_SCRIPTS["job_env.py"]

into your site environment script to indicate the you want the $JOB environment variable point to the directory where the 'job_env.py' file have been found.

Warning

Since keys are unique in a dictionary, and we didn’t want to overcomplicate things, there could be only one instance of a given filename in ENV_SCRIPTS. The rule is that the file higher in the filesystem hierarchy is the one that can be found in the dictionary.

The operator exports the global variables of the asset’s python module so it provides access to the hou module and the scene itself.

(Although this might be convenient, calling Houdini functions from env scripts break their application-independence.)

Special (Output) Variables

There are several special variables available that provide additional functionality.

MAPPINGS

You can define a dictionary called MAPPINGS that let the operator translate drive letters to UNC paths. For example 

MAPPINGS = {
        "x:": "//server/x",
        "l:": "//library/l",
        }

will translate x: to //server/x and l: to //library/l.

ENV_VAR_ORDER

With this variable you can determine the display order of the variables coming from the scripts. For example 

ENV_VAR_ORDER = [
        'JOB',
        'SCENE',
        'SCENE_NAME',
        ]

will cause JOB to be displayed first in the variable list if defined, followed by SCENE and SCENE_NAME. Any other variables that defined by the scripts will follow these in an arbitrary order.

OTL_PATTERN

A comma separated list of file patterns. The files mathcing the patterns will be imported as asset libraries. For example 

OTL_PATTERN = JOB + '/Asset/*/Otl/*.otl"

will import all otl files in the 'Otl' directories in the directories in the 'Asset' directory in your JOB directory.

Tip

You can add new patterns to OTL_PATTERN in different scripts to import scene or shot specific assets with simple string concatenation. 

OTL_PATTERN = OTL_PATTERN + ':' + SCENE + '/Otl/scene_specific.otl'

Parameters

Variables
Refresh

Refresh all the variables and imports otls defined in OTL_PATTERN.

Add New Variable

Creates a new variable on the interface. You should leave the override flag on for variables created with this method if you want to keep them during refresh.

(variable list)
Name

Name of the variable.

Value

Value of the variable.

Override

If this toggle is checked the value doesn’t get updated by the value defined in the scripts.

Delete

Delete variable from the interface and unset the the belonging variable.

Time
FPS

You can define the FPS of your scenes but you can’t override or delete it from the interface of Environment qL. Use standard methods if you want to change it temporarily.

Settings
Site Env File

An (optional) global environment script file with a specified path. (It doesn’t need to be within the path of the hip file.)

Env File Pattern

File name pattern for the env script files. Files matching this pattern will be treated as env scripts. (For available wildcards, see the python glob module.)

Refresh on File Load

Refreshes the environment on scene file open.

Convert Backslash

Convert backslashes to forward slashes. (Forward slashes work on all platform including Windows.)

Apply Path Mappings

Apply file system path mappings defined by the MAPPINGS variable.

Sort Variables

Sort variables according to the list in ENV_VAR_ORDER.

Import OTLs

Import OTL files matching the patterns defined in OTL_PATTERN.

Discard Special Variables

Discard variables that change the behavior of Environment qL itself (HIP, HIPNAME, ENV_SCRIPTS, ENV_SCRIPT_NAME, ENV_SCRIPT_PATH).

Use this toggle if you want to check their values on the interface.

Verbose (progress, debug)

Various levels of logging to the console (stderr).

If enabled, detailed progress messages are written to the console about all operations performed (to help pinpointing of possible issues).

Limitations

  • ...

To Do

  • Refactoring in progress –

    • Finalize way(s) of message outputs (options for verbose debugging (?), etc.)

    • Function for substituting a regular path into a variable-based one

    • Describe extra funcs in help: msg(), warn(), err()

    • ...

Release Notes

interface version 1 —

2014-10-04

  • err() now automatically dumps traceback

  • more informative messages in case of (python) errors in config files

2014-09-29

Internal refactoring and cosmetics –

  • Verbose logging of actions

  • Node is ignored if bypassed

  • Help card update

2012-12-05

Matured the scheme based on user feedback.

2012-11-01

Initial release.