Kitsu Service

This document will show you how we use python modules based interaction with the Kitsu API to integrate it with our other in-house pipeline tools.

Introduction

Kitsu is a third-party application developed and maintained by CG-Wire. It is used as a collaboration platform for animation, VFX, and game studios.

The CGIFilms pipeline heavily relies on Kitsu to integrate the following functionality into its system :

• Populating the Episode, Scene, Shot and Asset list for the entire project on the Kitsu database
• Creating a cast list by linking Assets and Shots in the Kitsu Breakdown view
• Assigning tasks to artists
• Tracking history and progress of tasks and artists
• Uploading preview files for reviews
• Providing review tools to supervisors to annotate and comment to share their feedback with the artists

External Dependencies

In order to develop python based tools with the ability to interact with Kitsu, you require two important modules :

• Zou - the Kitsu API
• Gazu - the Python client

Both Zou and Gazu further rely on many external libraries in order to function properly. All these libraries are collected on the server at :

\\path\to\python_modules\kitsu_packages\gazu_0.10.28

You can simply append this path at the start of your python script as shows below :

import sys
sys.path.append(r"\\path\to\python_modules\kitsu_packages\gazu_0.10.28")

This will give you access to all the required files without encountering any errors.

Using Gazu

Gazu is a Python client for the Kitsu API. It allows you to fetch your production data easily. More than giving access to data, it allows performing operations, like marking a task as started or setting a thumbnail on a shot.

To learn more, check out the Official Gazu Documentation.

Using Kitsu Service

Kitsu Service is a custom made python script developed by the CGIFilms team. It is a simplified version of the Gazu module and includes a limited set of the full API capabilities which are most commonly used by the CGIFilms pipeline tools.

The script file is located at :

"\\path\to\python_modules\cgif_toolset\kitsu_service.py"

In order to use Kitsu Service in your python script, do the following :

Now you have access to the KitsuModule object inside your code, and you can use it to fetch or update data from the Kitsu database. Let’s look at a few examples of how to use it.

Use Case : 01

1. Fetching Project Data from Kitsu Database

All your scripts will start with the code block mentioned above.
After that, try the following script :

# continued
10 kp.project     = 'PHICHKR'
11 print(kp.project)

This should print the all the details of the project PHICHKR in a python dictionary.

2. Fetching Shot Details

To fetch details of a particular shot, try the following script :

# continued
12 kp.sequence    = 'SEQ_001'
13 kp.shot        = 'SHOT_010'
14 print(kp.shot)
15 

This should print the all the details of the shot SHOT_010 in seq SEQ_001 in a python dictionary.

NOTE : We have to mention the sequence number in order to fetch the shot details, since a shot is considered an object of a sequence.

3. Adding Comments

To add a comment to a particular shot, try the following script :

# continued
16 kp.task_type    = 'PREP'
17 kp.task_status  = 'WIP'
18 kp.comment      = 'Aditya Hegade has started working on this shot'
19

Now if you open Kitsu and find your way to PHICHKR > SEQ_001 > SHOT_010 > PREP, you will see the status is set to WIP with the comment mentioned above.

NOTE : In order to set a comment, the Task Type and Task Status have to be mentioned. Also, notice that although we mentioned the ‘Aditya Hegade’ in the comment, the actual owner of the comment is ‘Kitsu Bot’, which is a bot account that we use while accessing Kitsu through the API.

4. Uploading Previews

To upload a preview, simply add this line with the path to the preview image/video file :

# continued
20 kp.task_status  = 'WFA'
21 kp.comment      = 'Aditya Hegade has uploaded a file for review'
22 kp.preview      = r"path\to\video\file\video_file.mp4"

Now if you check Kitsu again, you will find the specified image / video file has been uploaded to Kitsu with the updated comment, and the status is now set to WFA .

5. Compiled Code

This is how the complete code would look like :

10 kp.project     = 'PHICHKR'
11 print(kp.project)
12 kp.sequence    = 'SEQ_001'
13 kp.shot        = 'SHOT_010'
14 print(kp.shot)
15 
16 kp.task_type    = 'PREP'
17 kp.task_status  = 'WIP'
18 kp.comment      = 'Aditya Hegade has started working on this shot'
19
20 kp.task_status  = 'WFA'
21 kp.comment      = 'Aditya Hegade has uploaded a file for review'
22 kp.preview      = r"path\to\video\file\video_file.mp4"

Use Case : 02

1. Creating New Sequence and Shot

During Ingestion, we often need to create new entries for multiple sequences and shots. But before creating, we must first check if a sequence or shot with the same name exists already. This can be easily done using the following script :

10 kp.project               = 'PHICHKR'
11 kp._create_new_sequence  = True
12 kp._create_new_shot      = True
13 kp.sequence              = 'SEQ_test_002'
14 kp.shot                  = 'SHOT_test_020'

Now if you check Kitsu again, you will see the new sequences and shots are created just as we specified above.
Also, if you try to run the script again, nothing will happen, since we already have a sequence and shot with the same name.

Links

Explore the following sections to learn more: