studio/blender-studio-tools
13
32
Fork 19
Code Issues 20 Pull Requests 4 Projects Releases 1 Activity

Docs: Project Tools Update #156

Merged
Nick Alberelli merged 59 commits from :docs/project-tools-update into main 2023-10-19 22:21:50 +02:00
Conversation 0 Commits 59 Files Changed 27 +548 -371
27 changed files with 548 additions and 371 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

71
docs/.vitepress/config.ts
View File

@ -51,13 +51,6 @@ export default defineConfig({
items: [
{ text: 'Introduction', link: '/pipeline-overview/introduction'},
{ text: 'Design Principles', link: '/pipeline-overview/design-principles'},
{text: 'Quick Start',
collapsed: true,
items: [
{ text: 'Pipeline Setup', link: '/pipeline-overview/quick-start/setup'},
{ text: 'Pipeline Usage', link: '/pipeline-overview/quick-start/usage'},
]
},
{
text: 'Organization',
collapsed: true,
@ -142,23 +135,15 @@ export default defineConfig({
collapsed: false,
items: [
{
text: 'Project Setup',
text: 'Project Tools',
collapsed: true,
items: [
{ text: 'Intro', link: '/user-guide/project-setup/intro' },
{ text: 'SVN', link: '/user-guide/project-setup/svn' },
{
text: 'Workstation',
collapsed: true,
items: [
{ text: 'Introduction', link: '/user-guide/project-setup/workstations/introduction' },
{ text: 'Installing Software', link: '/user-guide/project-setup/workstations/installing-software' },
{ text: 'Running Blender', link: '/user-guide/project-setup/workstations/running-blender' },
{ text: 'Troubleshooting', link: '/user-guide/project-setup/workstations/troubleshooting' },
],
},
{ text: 'Project Overview', link: '/user-guide/project_tools/project-overview' },
{ text: 'Project Usage', link: '/user-guide/project_tools/project-usage'},
{ text: 'Project Blender', link: '/user-guide/project_tools/project-blender' },
],
},
{
text: 'Organization',
collapsed: true,
@ -174,20 +159,9 @@ export default defineConfig({
{
text: 'TD Guide',
collapsed: false,
collapsed: true,
items: [
{text: 'Project Setup', link: '/td-guide/project-setup'},
{
text: 'Workstation',
collapsed: true,
items: [
{ text: 'Overview', link: '/td-guide/workstations/overview'},
{ text: 'Installation', link: '/td-guide/workstations/installation'},
{ text: 'Maintenance', link: '/td-guide/workstations/maintaince'},
{ text: 'Render Farm', link: '/td-guide/workstations/render_farm'},
]
},
{text: 'Project Tools Setup', link: '/td-guide/project-tools-setup'},
]
},
{
@ -207,7 +181,36 @@ export default defineConfig({
{text: 'Asset Publishing', link: '/archive/pipeline-proposal-2019/asset-publishing/introduction'},
{text: 'Character Pipeline Assistant', link: '/archive/pipeline-proposal-2019/asset-publishing/character-pipeline-assistant'},
],
}
},
{
text: 'Gentoo',
collapsed: true,
items: [
{
text: 'TD',
collapsed: false,
items: [
{ text: 'Overview', link: '/gentoo/td/overview'},
{ text: 'Installation', link: '/gentoo/td/installation'},
{ text: 'Maintenance', link: '/gentoo/td/maintaince'},
{ text: 'Render Farm', link: '/gentoo/td/render_farm'},
],
},
{
text: 'User',
collapsed: false,
items: [
{ text: 'Introduction', link: '/gentoo/user/introduction' },
{ text: 'Installing Software', link: '/gentoo/user/installing-software' },
{ text: 'Running Blender', link: '/gentoo/user/running-blender' },
{ text: 'SVN', link: '/gentoo/user/svn' },
{ text: 'Troubleshooting', link: '/gentoo/user/troubleshooting' },
]
},
],
},
],
},
markdown: {

0
docs/td-guide/workstations/installation.md → docs/gentoo/td/installation.md
View File

13
docs/td-guide/workstations/maintaince.md → docs/gentoo/td/maintaince.md
View File

@ -17,7 +17,7 @@ are used in Gentoo see the [Gentoo Handbook](https://wiki.gentoo.org/wiki/Ebuild
2. `ssh user@build-server-addr` connect to your build server via ssh
3. Update the package recipes on the Build Server `emaint sync --repo blender-studio-overlay`
Once an update of the recipe is complete any affected packages can be installed our updated by following the [Installing Packages on Build Server](/td-guide/workstations/maintaince#installing-packages-on-build-server) guide.
Once an update of the recipe is complete any affected packages can be installed our updated by following the [Installing Packages on Build Server](/gentoo/td/maintaince#installing-packages-on-build-server) guide.
## Installing Packages on Build Server
Packages need to be compiled on the Build Server and marked with a date to be able to discovered by the workstations. Follow the below steps to install/update a package on the build server.
@ -30,11 +30,16 @@ Packages need to be compiled on the Build Server and marked with a date to be ab
::: info Info
The command `emerge --oneshot {package-name}` compiles package, but does not add the packages to the [@world](https://wiki.gentoo.org/wiki/World_set_(Portage)), this means these packages will be removed when running `--depclean`.. We add this because these packages are already pulled in by another set. So we don’t want to add it again to the @world set. To learn more visit the [Gentoo Handbook](https://wiki.gentoo.org/wiki/Emerge#:~:text=fetchonly%20%2D%2Demptytree%20%40world-,Do%20not%20add%20dependencies%20to%20the%20world%20file,-If%20a%20dependency)
:::
## Update Add-ons in `/shared/software/addons`
## Update Local Add-Ons
Add-Ons are locally stored in the following directories; `/usr/share/flamenco` and `/usr/share/blender_studio_tools`. These are updated by running the following commands. These directories are automatically updated daily by the Gentoo package manager.
```bash
emerge -1 blender-studio-tools
emerge -1 flamenco
```
The software inside the `shared/software/addons` directory are the [Blender Studio Pipeline Add-ons](/addons/overview) and any other Add-ons that need to be distributed to all Blender Studio Users. These Add-ons are considered Live Packages. Live Packages are packages that fetch updates from the source repository directly and are not tied to a specific release. To update packages not included in `/shared/software/addons` see [Installing Software](/user-guide/project-setup/workstations/installing-software)
1. Follow the instructions in [Installing Packages on Build Server](/td-guide/workstations/maintaince#installing-packages-on-build-server) using `blender-studio-tools` as the package name.
### How to update to specific version?

0
docs/td-guide/workstations/overview.md → docs/gentoo/td/overview.md
View File

2
docs/td-guide/workstations/render_farm.md → docs/gentoo/td/render_farm.md
View File

@ -43,7 +43,7 @@ The Blender add-on also needs to be reloaded, make sure that Blender is restarte
This section will only provide a quick rundown of how to update the Flamenco package that is part of the Render Farm setup.
For more details and how to update other packages, see the [Maintenance](/td-guide/workstations/maintaince) page.
For more details and how to update other packages, see the [Maintenance](/gentoo/td/maintaince) page.
::: info Note
The Flamenco package should already have the correct [USE flags](https://wiki.gentoo.org/wiki/Handbook:AMD64/Working/USE) configured.

4
docs/user-guide/project-setup/workstations/installing-software.md → docs/gentoo/user/installing-software.md
View File

@ -22,7 +22,7 @@ emerge is the default package manager, use emerge to install, update, and genera
**emerge** provides commands to install packages onto your system including any dependencies. You must be **root** to make changes via **emerge**. _In this example package name is **spotify**._
1. [Open Terminal and Become Root](/user-guide/project-setup/workstations/installing-software.md#open-terminal-and-become-root)
1. [Open Terminal and Become Root](/gentoo/user/installing-software.md#open-terminal-and-become-root)
2. Find avaliable packages using the `eix` for example: `eix spotify`
```bash
@ -68,7 +68,7 @@ Dependency resolution took 8.40 s.
In this example package name is **spotify**.
1. [Open Terminal and Become Root](/user-guide/project-setup/workstations/installing-software.md#open-terminal-and-become-root)
1. [Open Terminal and Become Root](/gentoo/user/installing-software.md#open-terminal-and-become-root)
2. Remove a package and it’s dependacies safely.
1. `emerge --deselect spotify`
2. `emerge --depclean`

0
docs/user-guide/project-setup/workstations/introduction.md → docs/gentoo/user/introduction.md
View File

16
docs/user-guide/project-setup/workstations/running-blender.md → docs/gentoo/user/running-blender.md
View File

@ -1,6 +1,9 @@
# Working with Blender
## Launch Blender from Taskbar/Start Menu
This will launch the Blender that is pre-installed on your workstation and updated daily via the package manager. Your Blender configuration including add-ons is stored at `$HOME/.config/blender/{version}/`
1. Search for Blender in your Application Launcher
2. The application with the exact name `blender` without any suffix is the latest build.
![Image of Blender Icon in KDE Taskbar/Start Menu](/media/user-guide/launch_blender.mp4)
@ -9,6 +12,9 @@
1. Open a new Terminal window
2. Type command `blender`
## Roll Back Blender Build
Your workstation's package manager will update blender daily, to roll back to a previous version follow the guide below.
1. Login as ********root******** user using `su`
2. Run `rollback_blender.sh` from any folder
@ -28,7 +34,7 @@
```
3. Select a build by enter a number and pressing Enter to confirm
## Build Blender Locallly
## Build Blender Locally
1. Download Git repo
@ -47,3 +53,11 @@
```
3. Find your built blender `cd ../build_linux`
## Debug Build
1. Search for Blender in your Application Launcher
2. The application with the exact name `blender debug` without any suffix is the latest build, it should have a grey icon.
<!---
TODO Add Image of Debug Build on Gentoo
--->

0
docs/user-guide/project-setup/svn.md → docs/gentoo/user/svn.md
View File

6
docs/user-guide/project-setup/workstations/troubleshooting.md → docs/gentoo/user/troubleshooting.md
View File

@ -16,11 +16,11 @@ _If successful, you will be greated with the following screen_
![IPXE Boot Menu](/media/user-guide/workstations/gentoo_boot_menu.png)
## Run MEM Test
1. [Boot into IPXE](/user-guide/project-setup/workstations/troubleshooting.md#run-mem-test)
1. [Boot into IPXE](/gentoo/user/troubleshooting.md#run-mem-test)
2. Select “Run MemTest”
## Chrooting into the root drive (for recovery)
1. [Boot into IPXE](/user-guide/project-setup/workstations/troubleshooting.md#run-mem-test)
1. [Boot into IPXE](/gentoo/user/troubleshooting.md#run-mem-test)
2. Select Gentoo Installer (Blender Institute Customized)
3. Wait for Gentoo Installer to boot ![Gentoo Installer](/media/user-guide/workstations/gentoo_installer_boot.png)
4. Use CTR+C to cancel Installer
@ -30,7 +30,7 @@ _If successful, you will be greated with the following screen_
## Recovery/Inspection of Linux Kernel
1. [Follow steps in Chrooting into the root drive](/user-guide/project-setup/workstations/troubleshooting.md#chrooting-into-the-root-drive-for-recovery)
1. [Follow steps in Chrooting into the root drive](/gentoo/user/troubleshooting.md#chrooting-into-the-root-drive-for-recovery)
2. Ensure the mount the boot drive is mounted **`mount /boot`**
3. Go into the kernel source dir **`cd /usr/src/linux`**
4. Use `make menuconfig` to enter linux kernel configuration

2
docs/index.md
View File

@ -11,7 +11,7 @@ hero:
link: /pipeline-overview/introduction
- theme: alt
text: User Guide
link: /user-guide/project-setup/intro
link: /user-guide/project_tools/project-overview
features:
- title: Free Software

BIN
docs/media/pipeline-overview/quick-start/kitsu_pref.png (Stored with Git LFS)
View File

Binary file not shown.

BIN
docs/media/pipeline-overview/quick-start/render_review_pref.png (Stored with Git LFS)
View File

Binary file not shown.

BIN
docs/media/td-guide/kitsu_pref.png (Stored with Git LFS) Normal file
View File

Binary file not shown.

BIN
docs/media/td-guide/render_review_pref.png (Stored with Git LFS) Normal file
View File

Binary file not shown.

40
docs/naming-conventions/shared-folder-structure.md
View File

@ -4,3 +4,43 @@
October 17th 2023 - The content of this page is currently being edited/updated.
:::
<!---
TODO Add logic & Introduction
--->
```bash
shared
├── artifacts # Where Global Blender & Add-Ons are stored
└── editorial
├── audio # Audio
├── deliver # Delivery for script
├── export # Renders coming out of edit
│ ├── _archive
│ │ └── gold-edit-v001_storyboard.mp4
│ ├── gold-edit-v001_previs.mp4
└── footage
├── sequences # Sequence Playblasts / Renders
│ ├── 010_intro
│ │ ├── 010_intro-beats
│ │ │ └── 010_intro-beats-v001.mp4
│ │ └── 010_intro-storyboards
│ │ └── ...
│ └── 020_water
│ └── ...
├── shots # Playblasts and Render Previews
│ ├── 010_intro
│ │ └── 010_0010
│ │ ├── 010_0010-previs
│ │ │ └── 010_0010-previs-v001.mp4
│ │ │ └── ...
│ │ └── 010_0010-animation
│ │ └── 010_0010-animation-v001.mp4
│ │ └── ...
│ └── 020_water
│ └── ...
└── frames # Render Review Output
└── 010_intro
└── 010_0010
```

34
docs/naming-conventions/svn-folder-structure.md
View File

@ -15,32 +15,32 @@ October 17th 2023 - The content of this page is currently being edited/updated.
* `maps` folder
## Proposal adopted in October 2023:
```
pro
├── assets
│ ├── chars
``` bash
pro # All files from the production
├── assets # All assets from the production
│ ├── chars # Characters & character variations
│ │ ├── dog
│ │ ├── cat
│ │ └── ..
│ ├── props
│ ├── props # Rigged props that can have animation
│ │ ├── rocket_exterior
│ │ ├── wings
│ │ └── ...
│ ├── sets
│ ├── sets # Static background elements
│ │ ├── barn
│ │ ├── rocket_interior
│ │ └── ...
│ ├── lib
│ ├── lib # Libraries of smaller assets
│ │ ├── rocks
│ │ ├── trees
│ │ ├── crates
│ │ └── ...
│ ├── maps
│ ├── lgt
│ ├── cam
│ ├── fx
│ ├── poses
│ ├── nodes
│ ├── maps # General textures and HDRIs
│ ├── lgt # Lighting setups
│ ├── cam # Camera rig
│ ├── fx # Effects
│ ├── poses # Pose libraries for animation
│ ├── nodes # General Node groups
│ └── scripts
├── shots
│ ├── 000_titles
@ -50,17 +50,19 @@ pro
│ ├── 900_animtest
│ └── 990_promo
└── config
pre
├── shots
pre # For pre-production
├── shots # Structured into sequences
└── assets
├── cam
├── char
└── ...
dev
dev # Anything related to early development or tests
├── concepts
├── boards
├── tests
└── ...
edit # Where the editorial .blend file lives
└── my_project_edit_v001.blend
.blender_project
promo
tools

4
docs/pipeline-overview/organization/infrastructure.md
View File

@ -10,8 +10,8 @@ Artists at Blender Studio use Linux workstations, running Gentoo Linux. While th
Artist workstations double as clients for the render farm.
* [**Link to reference manual**](/user-guide/project-setup/workstations/introduction.md)
* [**Link to setup guide**](/td-guide/workstations/overview.md)
* [**Link to reference manual**](/gentoo/user/introduction.md)
* [**Link to setup guide**](/gentoo/td/overview.md)
## Shared storage
We use two shared drives

175
docs/pipeline-overview/quick-start/setup.md
View File

@ -1,175 +0,0 @@
# Pipeline Setup
::: warning Work in Progress
15 Oct. 2023 - The content of this page is currently being edited/updated.
:::
## Introduction
In this guide, you will learn how to setup and use the Blender Studio Pipeline, the backbone of [Blender Open Movies](https://studio.blender.org/films/). This workflow relies on Blender, some Blender Add-Ons, and additional services like [Kitsu](https://www.cg-wire.com/kitsu) and [Flamenco](https://flamenco.blender.org/). 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 and use the pipeline, complete with easy-to-follow examples.
## 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.
```bash
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
```bash
mkdir /data/my_project
```
2. Navigate to the project-tools folder
```bash
cd /data/blender-studio-pipeline/scripts/project-tools
```
3. Create base folder structure using
```bash
./init_project_folder_structure.py /data/my_project
```
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
```bash
mkdir /data/my_project/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.
::: warning Work in Progress
15 Oct. 2023 - The following folder trees are out of data, and will soon be updated.
:::
### 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.
<!--- TODO Need to improve, ask Sebastian maybe --->
```bash
.
├── bts # Behind the scenes
├── concepts # Concept art and paintings
├── development # Piches and boards
├── edit # VSE Editing sequences/exports
├── inspiration # Various inspirations & references
├── music
├── planning
├── pr
├── resources
├── script # Latest scripts for the movie
├── shot_packs # Shots for sharing online
├── training # Training produced for the production
└── videoref # Video shoots from animators
```
### 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.
<!--- TODO Need to improve, ask Sebastian maybe --->
```bash
.
├── config
│ └── asset_pipeline_config
├── previz # Anything related to early development or pre-production tests
└── pro # All files from the production
├── promo # Promotional material. Often created near the end of production
├── animation_test # For pre-production
├── shot_builder # Studio tool configs
├── lib # All assets from the production
│ ├── brushes
│ ├── cam # Camera rig & setup
│ ├── char # Characters & character variations
│ ├── env # Environment asset libraries
│ ├── fx # Effects
│ ├── lgt # Lighting setups
│ ├── maps # General textures and HDRIs
│ ├── matlib # Materials
│ ├── nodes # General Node groups
│ ├── poselib # Pose libraries for animation
│ ├── props
│ ├── scripts
│ └── sets
└── shots #Structured into sequences
```
## 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](https://kitsu.cg-wire.com/installation/) for Kitsu Server
2. Upon entering the Kitsu web interface follow the [first production](https://kitsu.cg-wire.com/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
```bash
cd /data/my_project/svn/tools
./update_blender.py
```
This will download the latest blender to `/data/my_project/local/blender`
### Install Blender Add-Ons
2. Download required Add-Ons
```bash
mkdir /data/my_project/shared/artifacts/addons
cd /data/blender-studio-pipeline/scripts/pipeline-release
./package_local.py /data/my_project/shared/artifacts/addons
```
### 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](/pipeline-overview/quick-start/setup.md#kitsu-server-setup)*
- Username: `{username@studio.org}`
- Password: `{user_password}`
- Project Settings
- Select Production: Choose the current Production
- Project Root Directory: `/data/my_project/svn`
- Animation Tools
- Playblast directory: `/data/my_project/shared/shot_previews/`
![Blender Kitsu Preferences](/media/pipeline-overview/quick-start/kitsu_pref.png)
## 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/my_project/render/`
- Shot Frames: `/data/my_project/shared/shot_frames/`
- Shot Previews: `/data/my_project/shared/shot_previews/`
![Render Review Preferences](/media/pipeline-overview/quick-start/render_review_pref.png)
## Flamenco Setup
1. Create Flamenco shared storage directory
```bash
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/my_project/local/blender/{os}/blender` as the Blender Executable Path

79
docs/td-guide/project-setup.md
View File

@ -1,79 +0,0 @@
# Project Setup
::: warning Work in Progress
30 Apr. 2023 - The content of this page is currently being edited/updated.
:::
* Setup SVN (access for users)
* Setup Kitsu project
* Commit intial folder structure
## Project Directory
```python
.
├── config
│ └── asset_pipeline_config
├── previz # Anything related to early development or pre-production tests
└── pro # All files from the production
├── promo # Promotional material. Often created near the end of production
├── animation_test # For pre-production
├── shot_builder # Studio tool configs
├── lib # All assets from the production
│   ├── brushes
│   ├── cam # Camera rig & setup
│   ├── char # Characters & character variations
│   ├── env # Environment asset libraries
│   ├── fx # Effects
│   ├── lgt # Lighting setups
│   ├── maps # General textures and HDRIs
│   ├── matlib # Materials
│   ├── nodes # General Node groups
│   ├── poselib # Pose libraries for animation
│   ├── props
│   ├── scripts
│   └── sets
└── shots #Structured into sequences
```
## Render Directory
```
.
├── chaches
├── delivery
│   ├── audio
│   ├── color_preview
│   ├── mux
│   └── video
├── editorial
│   ├── edit
│   ├── export
│   ├── fonts
│   ├── score
│   └── sfx
├── farm_output
│   ├── lib
│   └── shots
├── plates
├── shot_frames
└── shot_previews
```
## Shared Directory
```python
.
├── bts # Behind the scenes
├── concepts # Concept art and paintings
├── development # Piches and boards
├── inspiration # Various inspirations & references
├── music
├── planning
├── pr
├── resources
├── script # Latest scripts for the movie
├── shot_packs # Shots for sharing online
├── training # Training produced for the production
└── videoref # Video shoots from animators
```

219
docs/td-guide/project-tools-setup.md Normal file
View File

@ -0,0 +1,219 @@
# Project Tools Setup
::: warning Work in Progress
15 Oct. 2023 - The content of this page is currently being edited/updated.
:::
## Introduction
In this guide, you will learn how to setup the Blender Studio Pipeline, the backbone of [Blender Open Movies](https://studio.blender.org/films/). This workflow relies on Blender, some Blender Add-Ons, and additional services like [Kitsu](https://www.cg-wire.com/kitsu) and [Flamenco](https://flamenco.blender.org/). 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.
```bash
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
```bash
mkdir /data/{my_project}
```
2. Navigate to the project-tools folder
```bash
cd /data/blender-studio-pipeline/scripts/project-tools
```
3. Create base folder structure using
```bash
./init_project_folder_structure.py /data/{my_project}
```
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)
```bash
mkdir /data/{my_project}/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.
#### Initial Directory Set-Up
1. Create your Shared Folder directly in the target directory or symlink it to`/data/{my_project}/shared`.
2. Use the following commands to generate the below folder structure.
```bash
cd /data/blender-studio-pipeline/scripts/project-tools
./init_folder_structure /data/{my_project}/shared shared_folder_structure.json
```
#### Add Existing Directory to User Workstation
1. Clone your SVN Folder directly into the target directory `/data/{my_project}/shared`.
```bash
shared
├── artifacts # Where Global Blender & Add-Ons are stored
└── editorial
├── audio # Audio
├── deliver # Delivery for script
├── export # Renders coming out of edit
│ ├── _archive
└── footage
├── sequences # Sequence Playblasts / Renders
├── shots # Playblasts and Render Previews
└── frames # Render Review Output
```
### 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.
#### Initial Directory Set-Up
1. Create your SVN Folder directly in the target directory `/data/{my_project}/svn`.
2. Use the following commands to generate the below folder structure.
```bash
cd /data/blender-studio-pipeline/scripts/project-tools
./init_folder_structure /data/{my_project}/svn svn_folder_structure.json
```
#### Add Existing Directory to User Workstation
1. Clone your SVN Folder directly into the target directory `/data/{my_project}/svn`.
```bash
.
└── 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](https://kitsu.cg-wire.com/installation/) for Kitsu Server
2. Upon entering the Kitsu web interface follow the [first production](https://kitsu.cg-wire.com/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
```bash
cd /data/{my_project}/svn/tools
./update_blender.py
```
This will download the latest blender to `/data/{my_project}/local/blender`
::: info Choosing Branch to Install
You can specify a [daily build](https://builder.blender.org/download/daily/) branch to fetch by editing the `BLENDER_BRANCH` variable in the script file.
:::
### Install Blender Add-Ons
2. Download required Add-Ons
```bash
mkdir /data/{my_project}/shared/artifacts/addons
cd /data/blender-studio-pipeline/scripts/pipeline-release
./package_local.py /data/{my_project}/shared/artifacts/addons
```
### Install Blender Icon
If a desktop icon is preferred to launch blender
```bash
cd /data/{my_project}/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](/td-guide/project-tools-setup.md#kitsu-server-setup)*
- Username: `{username@studio.org}`
- Password: `{user_password}`
- Project Settings
- Select Production: Choose the current Production
- Project Root Directory: `/data/{my_project}/svn`
- Animation Tools
- Playblast directory: `/data/{my_project}/shared/editorial/footage/shots/`
- Frames Directory: `/data/{my_project}/shared/editorial/footage/frames/`
- Editorial Export Directory (Optional)
- `/data/{my_project}/shared/editorial/export/`
<!--
TODO Replace Image
-->
![Blender Kitsu Preferences](/media/td-guide/kitsu_pref.png)
## 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/{my_project}/render/`
- Shot Frames: `/data/{my_project}/shared/editorial/footage/frames/`
- Shot Previews: `/data/{my_project}/shared/editorial/footage/shots/`
![Render Review Preferences](/media/td-guide/render_review_pref.png)
<!--
TODO Replace Image
-->
## Flamenco Setup
1. Create Flamenco shared storage directory
```bash
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/{my_project}/local/blender/{os}/blender` as the Blender Executable Path

13
docs/user-guide/project-setup/intro.md
View File

@ -1,13 +0,0 @@
# Project Setup
::: warning Work in Progress
30 Apr. 2023 - The content of this page is currently being edited/updated.
:::
Write how to set up a project in a fully configured workstation and production enviroment. Probably links to other parts of the reference.
* Ensure SVN access
* Ensure that Blender is configured with the 'shared' add-ons directory
* Ensure Kitsu access
* Checkout SVN project in the appropriate location
* ...

99
docs/user-guide/project_tools/project-blender.md Normal file
View File

@ -0,0 +1,99 @@
# Project Blender
Project Tools will store a version of Blender within the `shared` directory. This version of Blender is internal to that project. This allows for multiple Blenders to be installed on your system, each with their own preferences tailored specifically to that project. The main advantage to running/managing Blender using the Project Tools scripts is that it will synchronize the Blender version and Shared Add-Ons across for all users contributing the the project. Project Tools also allows you to run a custom build of Blender with the Add-Ons and preferences set for your project.
## Create Blender Shortcut
Once your project has been setup using the "Project Tools" scripts Blender should be available inside your application's native application launcher. The run Blender script will take the correct blender version for your operating system from `{my_project}/shared/artifacts/blender` and extract it to the local directory. Along with any add-ons in the `{my_project}/shared/artifacts/addons` folder. Your Blender preferences are stored on a per project basis in `{directory-path}`
### Create Linux Shortcut
```bash
cd {my_project}/svn/tools
./install_desktop_file.sh
```
::: info Available on Gentoo
To learn more about running the Blender if you are on a Gentoo system please see the [Gentoo guide](/gentoo/user/running-blender.md), including how to run a [debug build](/gentoo/user/running-blender.md#debug-build).
:::
#### Launch with Custom Build on Linux
You must run the Create Linux Shortcut step before running a custom build. This will launch blender using your custom binary, but with the Add-Ons and preferences of your project.
1. Navigate to your custom Blender binary
2. Right Click the binary
3. Select `Open with > Blender {my_project}`
<!---
TODO Replace Image with Project-Tools version
![Image of Blender Icon in KDE Taskbar/Start Menu](/media/user-guide/launch_blender.mp4)
--->
### Create Windows Shortcut
1. Open the directory `{my_project}/svn/tools`
2. Create a shortcut to `launch_blender_win.bat` on your desktop
### Create Mac Shortcut
1. Open the directory `{my_project}/svn/tools`
2. In finder, select the `launch_blender_mac.command` and press `ctrl+shift+command+t` to add it to the dock.
## Launch Blender from Terminal
To launch Blender from the terminal, open the tools directory within your project folder, and from the terminal use the run Blender script.
```bash
cd /{my_project}/svn/tools
./run_blender.py
```
::: warning Command Line Arguments
Note: Command Line Arguments also known as Flags are not supported by the `run_blender.py` script.
:::
## Update Blender
This script will fetch the latest Blender download from https://builder.blender.org/download/ The Blender download for Linux, Mac, and Windows will be downloaded into the `{my_project}/shared/artifacts/blender` folder. It will keep up to 10 previous downloaded versions for backup. This Blender doesn't update automatically, at least one user in the project must manually initiate an update, all users will receive this update because blender is stored within the `shared` directory.
::: info Blender Studio Users
Internally to the Blender Studio only, the blender inside your project is automatically updated overnight, not manual update is required.
:::
```bash
cd /{my_project}/svn/tools
./update_blender.py
```
## Rollback Blender
Use `rollback_blender.py` to switch the "current" version hosted in `{my_project}/shared/artifacts/blender` to one the older downloads, rolling back affects all users using your project. This is intended to be used to rollback to an older version in case of bugs in newer downloaded versions.
```bash
cd /{my_project}/svn/tools
./rollback_blender.py
```
### Rollback Blender Locally
In some cases user may want to roll their machine's local blender to a previous version without affecting other users.
```bash
cd /{my_project}/svn/tools
./rollback_blender_local.py
```
## Update Blender Add-Ons
Blender Add-ons can be packaged directly from the [Blender Studio Pipeline](https://projects.blender.org/studio/blender-studio-pipeline) repository. Personal Add-Ons can be installed [normally](https://docs.blender.org/manual/en/latest/editors/preferences/addons.html#installing-add-ons).
```bash
cd /blender-studio-pipeline/scripts/pipeline-release
./package_local.py /{my_project}/shared/artifacts/addons
```
::: info Blender Studio Users
Flamenco is installed and updated by the package manager of your Gentoo workstation. To learn more see [Update Local Add-Ons](/gentoo/td/maintaince#update-local-add-ons) in the Gentoo section.
:::

27
docs/user-guide/project_tools/project-overview.md Normal file
View File

@ -0,0 +1,27 @@
# Project Overview
## Introduction
"Project Tools" is a collection of scripts included in the [Blender Studio Pipeline](https://projects.blender.org/studio/blender-studio-pipeline) repository, developed to assist you in running and managing one or more projects. These scripts automate and standardize many common operations involved in setting up a production pipeline.
It all starts with the directory layout, which should be deployed by a Technical Director following the [Project Tools Setup Guide](/td-guide/project-tools-setup.md). This standard directory layout defines where things like .blend files and playblasts are stored. It enables project tools the ability to ensure all users are running the same Blender and have a similar experience with minimal setup required by the individual users.
## Directory Layout
Typically projects are stored at the following path `/data/{my_project}` where `data` is at the root of the filesystem. This is for consistency between computers at the Blender Studio. External studios can use a different root folder for their projects for example a user's home folder.
The project folder contains all data related to a project including .blend files, playblasts, the blender that is used on the project for all operating systems and even preferences are stored within the project.
* `local` This is where the local copy of Blender and the add-ons will be installed. This directory is populated by the `run_blender.py` script with the Blender & Add-Ons from `shared`.
* `shared` This is the folder that should be shared over the network, it contains renders, playblast and other items that don't require version control. (By using Syncthing, NFS shares, Samba, Dropbox, etc)
* `svn` This the versioned controlled folder where the .blend production files will live.
```bash
.
└── my_project/
├── local # The local copy of Blender and the add-ons will be installed.
├── shared # Shared over the network (Syncthing, NFS, Dropbox, etc)
└── svn # Contains the `.blend` production files. (SVN, GIT-LFS, etc)
```
To learn the layout of the above directories, see the [`shared`](/naming-conventions/shared-folder-structure.md) and [`svn`](/naming-conventions/svn-folder-structure.md) directory overviews.

52
docs/pipeline-overview/quick-start/usage.md → docs/user-guide/project_tools/project-usage.md
View File

@ -1,28 +1,16 @@
# Pipeline Usage
# Project Usage
Once your project is set-up there are several things that users can do when using the pipeline, including creating new shots on Kitsu directly from Blender, automatically building shots based on Kitsu data and updating the frame range of existing shots within the project.
::: warning Work in Progress
15 Oct. 2023 - The content of this page is currently being edited/updated.
:::
## Launching Blender
To launch Blender use the following command
```bash
cd /data/my_project/svn/tools
./run_blender.py
```
If a desktop icon is preferred to launch blender
```bash
cd /data/my_project/svn/tools
./install_desktop_file.sh
```
## Sync your Edit with Kitsu Server
Most productions begin with a previz or storyboard step, showing the overall direction and plan for the production. By inputting this as video strip(s) into a VSE file we can automatically create the corresponding shots on the Kitsu Server directly from the VSE.
1. If not already ensure your project settings are setup [Blender Kitsu Add-On Preferences](https://studio.blender.org/pipeline/addons/blender_kitsu#how-to-get-started)
2. At the directory `/data/my_project/shared/edit` create a new "Video Editing" File.
2. At the directory `{my_project}/svn/edit` create a new "Video Editing" File.
3. Populate your new edit file with your previz video strips
4. With your first strip selected, in the Blender Kitsu side panel of the VSE select "Create Metastrip Active Shot” to create a new metastrip.
5. Next select “Init Active Shot”, and enter the Shot and Sequence names you would like to submit to Kitsu.
@ -38,7 +26,7 @@ The next step is to create an asset and store that information into the Kitsu Se
1. Launch Blender via [Launching Software] Guide
2. Under `Edit>Preferences>Add-Ons` ensure `Asset Pipeline` is enabled
3. Follow the[ asset pipeline guide](https://studio.blender.org/pipeline/addons/asset_pipeline#how-to-get-started) to create a new asset (optional)
4. Save the above asset within the directory `/data/my_project/svn/pro/lib/char`
4. Save the above asset within the directory `{my_project}/svn/pro/assets/char`
5. Create a matching entry in Kitsu for the above asset via the [Create Assets guide](https://kitsu.cg-wire.com/first_production/#create-assets)
6. Follow the [casting guide](https://forum.cg-wire.com/t/breakdown-casting-widget-for-kitsu/31) in the breakdown section to assign assets to shots.
@ -47,12 +35,12 @@ The next step is to create an asset and store that information into the Kitsu Se
Inside your production’s directory the Shot Builder configuration files need to be created using the [examples](https://projects.blender.org/studio/blender-studio-pipeline/src/branch/main/scripts-blender/addons/blender_kitsu/shot_builder/docs/examples) included in the Add-On directory. See the Shot Builder Config [Directory Layout](https://projects.blender.org/studio/blender-studio-pipeline/src/branch/main/scripts-blender/addons/blender_kitsu/shot_builder/docs#directory-layout) for details. The only configuration file that requires production specific edits is `assets.py`. This configuration file links the Kitsu Asset entries to their corresponding files in the production directory.
1. Copy Configuration Files from [examples](https://projects.blender.org/studio/blender-studio-pipeline/src/branch/main/scripts-blender/addons/blender_kitsu/shot_builder/docs/examples) to `/data/my_project/svn/pro/shot-builder/`
2. Update `assets.py` file with each asset you have in your `lib` folder see the [Shot Builder API](https://projects.blender.org/studio/blender-studio-pipeline/src/branch/main/scripts-blender/addons/blender_kitsu/shot_builder/docs#api)
3. Ensure your camera rig is present at the path `/data/my_project/svn/pro/lib/cam/camera_rig.blend`
1. Copy Configuration Files from [examples](https://projects.blender.org/studio/blender-studio-pipeline/src/branch/main/scripts-blender/addons/blender_kitsu/shot_builder/docs/examples) to `{my_project}/svn/pro/shot-builder/`
2. Update `assets.py` file with each asset you have in your `assets` folder see the [Shot Builder API](https://projects.blender.org/studio/blender-studio-pipeline/src/branch/main/scripts-blender/addons/blender_kitsu/shot_builder/docs#api)
3. Ensure your camera rig is present at the path `{my_project}/svn/pro/assets/cam/camera_rig.blend`
4. Open a new Blender File, select `File>New>Shot File`
5. Select the desired Sequence/Shot from Kitsu and select OK to start Building
6. New file will be saved to `/data/my_project/svn/pro/shots/{sequence}/{shot}/{shot}.blend
6. New file will be saved to `{my_project}/svn/pro/shots/{sequence}/{shot}/{shot}.blend
## Playblast your First Shot
Once your first shot is animated you are ready to render a playblast of this shot, which will be later imported into your edit .blend file.
@ -69,19 +57,19 @@ For each new task type, Anim/Layout etc needs to be added manually, then it can
Returning to your edit .blend file, we can now load the playblast from the animation file into the edit.
1. Open your edit .blend file inside the directory `/data/my_project/shared/edit`
1. Open your edit .blend file inside the directory `/{my_project}/svn/edit`
2. From the Sequencer Header select `Add>Movie`
3. Navigate to the directory of the playblast for your shot's .blend file `/data/my_project/shared/shot_previews/{sequence_name}/{shot_name}/{file_name}` and select the `.mp4` file
3. Navigate to the directory of the playblast for your shot's .blend file `{my_project}/shared/footage/shots/{sequence_name}/{shot_name}/{file_name}` and select the `.mp4` file
4. Place the new shot at the same timing as the corresponding metastrip
## Adjusting a Shot's Frame Range
During production in some cases the frame range of a shot will change, either adjusting a shot's length or adjusting it's position in the edit. Once adjusted, we can update the shot .blend file's frame range so new playblasts will match this updated frame range. Once a new playblast is available the shot can automatically be updated in the VSE via the Blender Kitsu Add-On
1. Open your edit .blend file inside the directory `/data/my_project/shared/edit
1. Open your edit .blend file inside the directory `{my_project}/svn/edit`
2. Select a shot and it's metastrip, adjust the timing of both strips so they remain in sync.
3. Select your metastrip, in the Kitsu Sidebar of the VSE Under Push select `Metadata 1 Shot` to push your shot's new frame range to the Kitsu Server
4. Open your shot .blend file inside the directory
`/data/my_project/svn/pro/shots/{sequence_name}/{shot_name}/
`{my_project}/svn/pro/shots/{sequence_name}/{shot_name}/`
5. Inside the Kitsu Sidebar, under Playblast tools, if your frame range on Kitsu has changed you will see a red `Pull Frame Range` button. Select it to update the file's Frame Range
6. Adjust the shot's animation to accommodate the new frame range, then under Playblast use the `+` button to create a new version, then select `Create Playblast` to render a new playblast
7. Open your edit .blend file, and select the movie strip for the shot you would like to update.
@ -96,7 +84,7 @@ Once your shots are all ready to go, you can now render a final EXR from each of
3. In the properties panel navigate under Flamenco
1. Select `Fetch Job Types`
2. From the Dropdown select `Simple Blender Render`
3. Set Render Output Directory to `/data/my_project/render/`
3. Set Render Output Directory to `{my_project}/render/`
4. Set Add Path Components to `3`
5. Finally Select `Submit to Flamenco`
@ -108,8 +96,8 @@ Once your shot(s) have been rendered by Flamenco, you are ready to review your r
3. From the dialogue box select a Sequence Name you would like to Review
4. Select the video strip for the render you are reviewing
5. Select `Push to Edit & Approve Render`
- Push to Edit will take the mp4 of your flamenco render and add it to the `shot_previews` directory
- Approve Render will copy the Image Sequence of your flamenco render to the `shot_frames` directory
- Push to Edit will take the mp4 of your flamenco render and add it to the `{my_project}/shared/editorial/shots` directory
- Approve Render will copy the Image Sequence of your flamenco render to the `{my_project}/shared/editorial/frames` directory
## Import Approved Renders into VSE
Renders approved by the render review Add-On can be automatically imported into your edit using the same function used to update the playblast of shots in the edit.
@ -123,16 +111,16 @@ Once the approved image sequences have been loaded into the main edit you are re
1. Open your Edit .blend file
2. Render Video as PNG Sequence
1. Under `Properties>Output` Set the output directory to `/data/my_production/shared/edit/delivery/frames/`
1. Under `Properties>Output` Set the output directory to `{my_project}/shared/editorial/deliver/frames/`
2. Set the File Format to `PNG`
3. Select `Render>Render Animation`
3. Render Audio
1. Select `Render>Render Audio`
2. In the Side Panel select Container `.wav`
3. Set the output directory to `/data/my_production/shared/edit/delivery/audio/`
3. Set the output directory to `{my_project}/shared/editorial/deliver/audio/`
4. Run Deliver script
1. Copy the `delivery.py` from `/data/blender-studio-pipeline/film-delivery/` to the directory `/my_production/shared/edit/delivery/`
2. Enter delivery directory `cd /my_production/shared/edit/delivery/
1. Copy the `delivery.py` from `{my_project}/blender-studio-pipeline/film-delivery/` to the directory `/{my_project}/shared/editorial/deliver/`
2. Enter delivery directory `cd /{my_project}/shared/editorial/deliver/
3. Encode audio with `./deliver.py --encode_audio audio/{name_of_audio}.wav`
4. Encode video with `.deliver.py --encode_video frames/`
5. Finally `.delivery.py --mux`

16
scripts/project-tools/shared_forder_structure.json Normal file
View File

@ -0,0 +1,16 @@
{
"": {},
"artifacts": {},
"editorial": {
"export": {
"_archive": {}
},
"deliver": {},
"footage": {
"frames": {},
"shots": {},
"sequences": {}
},
"audio": {}
}
}

31
scripts/project-tools/svn_forder_structure.json Normal file
View File

@ -0,0 +1,31 @@
{
"": {},
"dev": {
"concepts": {},
"tests": {},
"boards": {}
},
"edit": {},
"pro": {
"shots": {},
"config": {},
"assets": {
"chars": {},
"fx": {},
"scripts": {},
"cam": {},
"props": {},
"poses": {},
"maps": {},
"nodes": {},
"lgt": {},
"sets": {},
"lib": {}
}
},
"pre": {
"shots": {},
"assets": {}
},
"tools": {}
}