blender-studio-pipeline/docs/td-guide/project-tools-setup.md

Project Tools Setup

::: warning Linux & Mac Only The terminal commands on this page are designed to be run on a linux/mac systems. Commands require modifications to file paths to run on Windows. :::

Introduction

In this guide, you will learn how to setup the Blender Studio Pipeline, the backbone of Blender Open Movies. This workflow relies on Blender, some Blender Add-Ons, and additional services like Kitsu and Flamenco. Wether you are an individual with a single computer or a studio with a full network of workstations, this guide offers a straightforward approach to set up the pipeline, complete with easy-to-follow examples.

::: info Python Requirement Running these scripts requires python 3.11+, please ensure python is installed on your system before running blender with the below instructions :::

Clone Repository

The Blender Studio Pipeline git repository contains many tools and resources used in deploying and managing a Blender Studio Pipeline. To start our pipeline we will need to clone this repository.

cd /data # This directory is the root storage that will contain all projects
git lfs install # Ensure git-lfs is installed
git clone https://projects.blender.org/studio/blender-studio-pipeline.git

Generate Folder Structure

The first step in deploying the Blender Studio Pipeline is to create the correct folder structure. Many of the tools used in the Blender Studio require the following folder structure on each of your studio workstations.

1. Create project root directory

mkdir /data/your_project_name

2. Navigate to the project-tools folder

cd /data/blender-studio-pipeline/scripts/project-tools

3. Create base folder structure using

./init_project_folder_structure.py /data/your_project_name 

This will create the bones of your production's directories.

• local This is where the local copy of Blender and the add-ons will be installed.
• shared This is the folder that should be shared over the network.
• svn This the versioned controlled folder where the .blend production files will live.

3. Create render directory (Optional)

mkdir /data/your_project_name/render/

This directory is used for the temporary storage of render files generated by Flamenco. This storage must be accessible by all computers using Flamenco for rendering, commonly this is a Network Attached Storage of some kind. In this guide, our renders will live in the root of our project directory.

Populating shared

This is the folder that should be shared over the network. (By using Syncthing, NFS shares, Samba, Dropbox, etc) Connect this folder to your sharing software of choice and create the following folder structure. More details about shared folder structure can be found here

Initial Directory Set-Up

1. Create your Shared Folder directly in the target directory or symlink it to/data/your_project_name/shared.
2. Use the following commands to generate the below folder structure.

   cd /data/blender-studio-pipeline/scripts/project-tools
   init_project_folder_structure.py /data/your_project_name/shared --json_file folder_structure_shared.json
   

Add Existing Directory to User Workstation

1. Clone your SVN Folder directly into the target directory /data/your_project_name/shared.

shared
├── artifacts # Where Global Blender & Add-Ons are stored
└── editorial   
    ├── audio # Audio
    ├── deliver # Delivery for script
    ├── export # Renders coming out of edit
    │   ├── _archive
    └── footage 
        ├── dev # Early Development
        ├── pre # Pre-Production steps like previs
        ├── pro # Playblast from Production
        └── post # Image Sequences/Final Renders

Populating SVN

This is the folder that should contain a version controlled file system to be shared over the network. (By using SVN, GIT-LFS, etc). Connect this folder to your version control software of choice and create the following folder structure. More details about shared folder structure can be found here

Initial Directory Set-Up

1. Create your SVN Folder directly in the target directory /data/your_project_name/svn.
2. Use the following commands to generate the below folder structure.

   cd /data/blender-studio-pipeline/scripts/project-tools
   init_project_folder_structure.py /data/your_project_name/svn --json_file folder_structure_svn.json
   

Add Existing Directory to User Workstation

1. Clone your SVN Folder directly into the target directory /data/your_project_name/svn.

.
└── svn  /
    ├── dev / # Anything related to early development or tests
    │   ├── boards
    │   ├── concepts
    │   └── tests
    ├── pre/ # For pre-production
    │   ├── assets
    │   └── shots
    ├── edit # Where the editorial .blend file lives
    ├── pro/ # All files from the production
    │   ├── assets/ # All assets from the production
    │   │   ├── cam # Camera rig & setup
    │   │   ├── chars # Characters & character variations
    │   │   ├── fx # Effects
    │   │   ├── lgt # Lighting setups
    │   │   ├── lib
    │   │   ├── maps # General textures and HDRIs
    │   │   ├── nodes # General Node groups
    │   │   ├── poses # Pose libraries for animation
    │   │   ├── props
    │   │   ├── scripts
    │   │   └── sets
    │   ├── config
    │   └── shots #Structured into sequences
    └── tools

Kitsu Server Setup

Kitsu is a project management software used by the Blender Studio for task management. The server is used to assign tasks to artists, as well as a track each shot as it moves through production The Kitsu server is required for automatically building shots.

1. Follow the Official setup instructions for Kitsu Server
2. Upon entering the Kitsu web interface follow the first production guide

Blender Setup

The next step is to deploy the required software onto each of the studio's workstations.

1. Download the latest Blender

cd /data/your_project_name/svn/tools
./update_blender.py

This will download the latest blender to /data/your_project_name/local/blender

::: info Choosing Branch to Install You can specify a daily build branch to fetch by editing the BLENDER_BRANCH variable in the script file. :::

Install Blender Add-Ons

2. Download required Add-Ons

mkdir /data/your_project_name/shared/artifacts/addons
cd /data/blender-studio-pipeline/scripts/pipeline-release
./package_local.py /data/your_project_name/shared/artifacts/addons

Install Blender Icon

If a desktop icon is preferred to launch blender

cd /data/your_project_name/svn/tools
./install_desktop_file.sh

::: warning Linux only feature October 19th 2023 -This feature is only available on linux at this time. Mac & Windows Users must launch Blender via the terminal. :::

Setup Blender Add-Ons

3. Follow the below instructions to correctly set the preferences of each Add-On

Blender Kitsu Add-On Preferences

1. Open Blender and Select Edit>Preferences>Add-Ons
2. Search the 'Blender Kitsu' and use the checkbox to Enable the Add-On
3. Set the following settings in the add-on preferences
   • Login
     • Host: {my_kitsu_server_url} Set during Kitsu Server Setup
     • Username: {username@studio.org}
     • Password: {user_password}
   • Project Settings
     • Select Production: Choose the current Production
     • Project Root Directory: /data/your_project_name/svn
   • Animation Tools
     • Playblast directory: /data/your_project_name/shared/editorial/footage/pro/
     • Frames Directory: /data/your_project_name/shared/editorial/footage/post/
   • Editorial Export Directory (Optional)
     • /data/your_project_name/shared/editorial/export/

Render Review Add-On Preferences

1. Open Blender and Select Edit>Preferences>Add-Ons
2. Search the 'Render Review' and use the checkbox to Enable the Add-On
3. Set the following settings in the add-on preferences
   • Ensure Enable Blender Kitsu is Enabled
   • Render Farm: /data/your_project_name/render/
   • Shot Frames: /data/your_project_name/shared/editorial/footage/post/
   • Shot Previews: /data/your_project_name/shared/editorial/footage/pro/

Flamenco Setup

1. Create Flamenco shared storage directory

mkdir /data/flamenco_storage

1. Follow the instructions at https://flamenco.blender.org/usage/quickstart/ to setup Flamenco
2. During Flamenco Manager Setup use /data/flamenco_storage as the shared storage directory
3. During Flamenco Manager Setup use /data/your_project_name/local/blender/{os}/blender as the Blender Executable Path