ShotRunner Python API Documentation v0.95

Rev: 8-Mar-2010

To Add: Introduction. What can you do with the API? What skills are needed? Table of Contents.

Installation

Download the zip file which contains the base classes, libraries and lots of sample scripts. Simply unpack the zip file into a directory of your choice.

Be sure you are running Python 2.5 or later. I'm pretty sure that Python 3.0 is not supported yet.

You should double-check that I didn't inadvertently include any *.pyc files in the distribution. I try to catch them every time, but if I forget and they are in there, the examples won't run.

Run the 000_setup_config.py first to setup a configuration file containing your user login if you want to change it from the default which is sam/sam1 at tutorial.shotrunner.com.

NOTE: The encryption used to store the password in the file is minimal, meant to only protect against casual onlookers. You should protect the config file as you would a private key file.

Samples

The example scripts are organized thus:

• 001-099 Utility scripts and tests
• 100-109 Basic samples
• 110-199 More complex examples
• 200-299 Integration examples
• 300-399 Real-world examples

Configuration

You can either setup a configuration file with your username, password and domain prefix (preferred), or you can call the login() method in your script.

To use the configuration file, first run: 000_setup_config.py and answer the questions. Then put the following in your script:

# Read in SR configuration including user login and account info
ShotRunner.init()

To use the login method, put this in your script:

# Set user credentials and account info
ShotRunner.set_login('sam', 'sam1', 'tutorial')

Dependencies

You need to have both the pyactiveresource/ and shotrunner/ directories where you have your scripts -- or, you need to modify the python module search path to include them.

The module search path can be changed by setting the PYTHONPATH environment variable before you run python. Let's say I wanted to place the shotrunner/ and pyactiveresource/ directories in a folder called 'python' in my home directory:

$ export PYTHONPATH=~/python

Once in python, you can see what the current module search path is:

>>> import sys
>>> print sys.path
>>> from shotrunner.base import ShotRunner

The other way to do it is to append the sys.path from within python:

>>> sys.path.append('/Users/cameron/python')
>>> from shotrunner.base import Sequence

Objects

Below is a diagram showing the relationships of the various objects that you can access via the API. After that, each object type is discussed in detail.

db_schema_rev_09.pdf

ShotRunner

Class Methods:

def set_login(user_=None, pass_=None, domain_=None):

def init(filename="sr.config"):

def debug(level=logging.INFO):

Project

A film, show, commercial or episode that is to be tracked by the system. A project has many members, is produced by a particular company, and is a container for sequences, shots, elements, assets, tasks, notes and files.

Attributes:

integer  id -- Unique index
string   code -- The project label
string   title
text     description -- Can contain textile markup
datetime due_date -- Date that work on the project is scheduled to end
string   status -- The status code, map using the `Code` object
integer  sponsor_id -- The company or vendor responsible for this project. Map to `Company` object.
integer  logo_image_id -- file handle of thumbnail. Use the main file, not one of the thumbnail sizes, the thumbnail size will be chosen depending on the display context.
integer  default_team_id
string   homepage_url -- Informational URL
integer  sort_order -- The order that projects are displayed in the Web UI

Read only:
string   created_by -- Login of user who created record
string   updated_by -- Login of last user to update record
datetime created_at
datetime updated_at
datetime deleted_at

Sequence

A sequence is a grouping of shots. Usually the shots in a sequence are similar, sharing common visual or post-process characteristics. A sequence has many shots and belongs to one project.

integer  "id"
string   "sequence_code"
string   "title"
text     "description"
string   "status"
integer  "sort_order"
integer  "project_id" -- Project

Read only:
datetime "created_at"
datetime "updated_at"
integer  "lock_version"

Shot

This is the basic unit of work on a VFX project. Generally an unedited, contiguous unit of action as viewed through one camera. Everything pretty much revolves around getting shots done. A shot belongs to one project and one sequence.

integer  "id"
integer  "sequence_id" -- Sequence
string   "shot_code"
string   "title"
text     "description"
string   "thumbnail_loc" -- Image URL
integer  "supervisor_id" -- Lead artist, User
string   "status" -- Code -- Code
integer  "frame_count"
integer  "sort_order"

Read only:
string   "created_by"
string   "updated_by"
datetime "created_at"
datetime "updated_at"
integer  "lock_version"

Element

Elements are subordinate to Shots, and generally represent the various layers in a composite. They are the unique visual or audible layers that need to be created and tracked in order for the shot or another Element to be completed. Each element may require one or more tasks to bring it to its final state. See: Can you explain Elements?.

integer  "id"
string   "element_type" -- Code
string   "label"
string   "title"
text     "description"
string   "thumbnail_loc" -- Image URL
string   "status" -- Code
integer  "supervisor_id" -- Lead artist, User
integer  "shot_id" -- Shot
integer  "asset_id" -- Asset
integer  "sort_order"

Read only:
string   "created_by"
string   "updated_by"
datetime "created_at"
datetime "updated_at"
integer  "lock_version",  :default => 0

Asset

Assets represent things produced outside of shots (say, in pre-production) or that are used across several shots. These can be things like 3D models, HDRIs, matte paintings, miniature sets or models, props, characters, etc. You can link assets to shots via elements. If you do this, then on the assets page you will see a list of all the shots where the asset is used. See: Can you explain Assets to me?.

integer  "id"
string   "asset_type" -- Code
string   "asset_label"
string   "title"
text     "description"
string   "thumbnail_loc" -- Image URL
string   "status" -- Code
integer  "supervisor_id" -- Lead artist, User
integer  "sequence_id" -- Sequence
integer  "team_id" -- Team
integer  "project_id" -- Project
integer  "company_id" -- Unused
integer  "sort_order"

Read only:
string   "created_by"
string   "updated_by"
datetime "created_at"
datetime "updated_at"
integer  "lock_version",  :default => 0

Task

The work to be done on an asset, sequence, shot, or an element of a shot.

integer  "id"
integer  "taskable_id"
string   "taskable_type"
string   "title"
text     "description"
integer  "skill_id" -- Category
integer  "user_id" -- User
string   "status" -- Code
datetime "start_date"
datetime "due_date"
datetime "end_date"
float    "estimated_time"
integer  "pct_complete",   :default => 0

Read only:
string   "created_by"
string   "updated_by"
datetime "created_at"
datetime "updated_at"

Note

Modeled after a forum or message board, a general-purpose way to annotate just about anything. Notes can be added at the project, sequence, shot, element, asset or task level. Uses include: status reporting, submissions and feedback, questions and answers, pointers to offsite reference, and ad-hoc data. Each note has an author, and can have a number of 'watchers' that receive email notification when the note is created or responded to.

integer  "id"
string   "noteable_type"
integer  "noteable_id"
string   "title"
text     "message"
integer  "user_id" -- User
string   "note_type" -- Code
integer  "parent_id" -- Note

Read only:
datetime "created_at"
datetime "updated_at"

Terms: A 'forum' is the discussion area on a particular object, which consists of a number of 'threads', which consist of a number of 'notes'. Users 'subscribe' to objects, and 'watch' threads.

Attachments

Images, video or other kinds of files can be attached to projects, sequences, shots, elements, assets, and tasks. Images can optionally be designated as the thumbnail for that object.

integer  "id"
string   "title"
text     "description"
integer  "attachment_container_id"
string   "attachment_container_type"
integer  "project_id" -- Project

Read only:
datetime "created_at"
datetime "updated_at"
string   "created_by"
string   "updated_by"

Note: Attachments/Files API under construction.

User

Account administrators can invite users to be members of projects. Everyone who uses the system has a login and password. In addition, we store basic contact information to make it easy for project members to communicate. Users can be members of many projects. Some users will be designated as administrators.

integer  "id"
string   "login"
boolean  "admin" -- True if user is an administrator
string   "status" -- Code, default => "P"
string   "first_name"
string   "last_name"
string   "email"
integer  "company_id" -- Company
string   "title"
string   "department",                :limit => 40
string   "address_line1",             :limit => 40
string   "address_line2",             :limit => 40
string   "city",                      :limit => 25
string   "state",                     :limit => 2
string   "zipcode",                   :limit => 10
string   "country"
string   "time_zone"
string   "work_phone",                :limit => 20
string   "home_phone",                :limit => 20
string   "cell_phone",                :limit => 20
string   "im_addr"
string   "im_type",                 :default => "AIM"
string   "skype_name"

Read only:
datetime "created_at"
datetime "updated_at"
object   company

Company

Users are employed by companies. Company affiliation is used both for identification purposes, and so that the "primary" company, that is, the company of the account holder, can have additional privileges. Projects will also be identified with a company, i.e. the "client" or "vendor" for a project. Project-Company combinations can be set up to ensure that vendors can not see each others' sensitive data.

integer  "id"
string   "name"

Read only:
datetime "created_at"
datetime "updated_at"

Member

Associates a user to a project, with a team and a role.

integer  "id"
string   "title" -- unused
integer  "user_id" -- Teamlead, map to User
integer  "project_id" -- Project
integer  "team_id" -- Team
integer  "role_id" -- Role

Read only:
datetime "created_at"
datetime "updated_at"

Team

Each user may be associated with a team. This is simply a way to group users into functional areas. Each team has a team lead, and can contain a description, website URL, team mail list and other information that the team lead may want to make available regarding the team. A user can belong to one team on one project, and another team on another project.

integer  "id"
string   "code"
string   "name"
text     "description"
string   "web_page"
string   "email"
integer  "teamlead_id" -- User
integer  "project_id" -- Project
integer  "parent_id" -- Team

Read only:
datetime "created_at"
datetime "updated_at"

Role

A collection of rights. Granted to a user via a project membership.

integer  "id"
string   "name"
integer  "position" -- UI sorting order
boolean  "is_default"

Read only:
datetime "created_at"
datetime "updated_at"

Code

This is a utility table that stores all of the various status codes, element types, task types, note types and other categories needed by the system. This allows a producer to change the terminology used on a particular project and to add new types.

integer  "id"
string   "scope" -- The group or category
string   "code" -- The actual code used as the foreign key
string   "label" -- Short identifier used in the UI
string   "meaning" -- Short description, used in tooltips and select lists
text     "description" -- Longer description, used in help text
boolean  "default"
string   "color"
integer  "sort_order"

Read only:
datetime "created_at"
datetime "updated_at"
datetime "deleted_at"

Class Hierarchy Diagram

Here is a diagram showing the class hierarchy: