Pipeline

This section of the manual focuses on the integration of Blender into a production pipeline. This is a vast topic that covers many areas of the software, but here we will focus on file/asset management and data I/O.

Note

The tools and workflows documented here require familiarity with working with a command line interface and are mostly aimed at TDs and technical users.

BAM Asset Manager

Refactoring linked .blend files is a common practice in a production environment. While some basic operations can be accomplished within Blender, sometimes it is more practical to perform them on the command line or via a script. During the production of Cosmos Laundromat (Gooseberry Open Movie Project) the BAM Asset Manager (BAM) was developed. The original scope of BAM included client-server asset management tools going beyond Blender, but it was later refocused on core utilities to perform two operations:

  • Blend-file packing
  • Automatic dependencies remapping

The following section of the manual focuses on how to use BAM.

Installing BAM

BAM is a standalone Python package, that can be run on any system without any particular configuration. The only requirement is Python 3 (and pip, the Python package manager, to easily install BAM).

Windows, Linux and macOS provide different ways to install Python 3 and pip. Check out the online docs to learn more about a specific platform.

Once Python 3 and pip are available, BAM can be installed via command line by typing:

pip3 install blender-bam

After a successful installation, the bam command will be available. By typing it and pressing the Enter key, all the available subcommands will be displayed.

bam pack

This command is used for packing a .blend file and all its dependencies into a .zip file for redistribution.

usage: bam pack [-h] [-o FILE] [-m MODE] [-e PATTERNS] [-a] [-q] [-c LEVEL]
             paths [paths ...]

You can simply pack a blend file like this to create a zip-file of the same name.

bam pack /path/to/scene.blend

You may also want to give an explicit output directory. The example shows how to pack a blend with maximum compression for online downloads

bam pack /path/to/scene.blend --output my_scene.zip --compress=best

The command provides several options to adapt to different workflows (final distribution, partial extraction, rendering).

-o, --output <FILE>
Output file or a directory when multiple inputs are passed.
-m, --mode <MODE>
Output file or a directory when multiple inputs are passed. Possible choices: ZIP, FILE.
-e, --exclude <PATTERN(S)>

Optionally exclude files from the pack.

--exclude="*.png"
Using Unix shell-style wildcards (case insensitive).
--exclude="*.txt;*.avi;*.wav"
Multiple patterns can be passed using the ; separator.
-a, --all-deps
Follow all dependencies (unused indirect dependencies too).
-q, --quiet
Suppress status output.
-c, --compress <LEVEL>
Compression level for resulting archive. Possible choices: default, fast, best, store.
--repo <DIR PATH>
Specify a “root” path from where to pack the selected file. This allows for the creation of a sparse copy of the production tree, without any remapping.
--warn-external
Report external libraries errors (missing paths).

Examples

Consider the following directory layout, and in particular the file 01_01_A.lighting.blend with its linked libraries.

~/agent327/
└─ lib/
   ├─ chars/
   |  ├─ agent.blend  ------------->|
   |  ├─ boris.blend  ------------->|
   |  └─ barber.blend               |
   └─ scenes/                       |
      ├─ 01-opening                 |
      ├─ 01_01_A.lighting.blend  <--|  < BAM pack this file
      └─ 01_01_A.anim.blend  ------>|

Once we run bam pack /scenes/01-opening/01_01_A.lighting.blend we obtain a 01_01_A.lighting.zip inside of which we find the following structure.

~/01_01_A.lighting
   ├─ 01_01_A.lighting.blend
   └─ __/
      ├─ 01_01_A.anim.blend
      └─ __/
         └─ lib/
            └─ chars/
               ├─ agent.blend
               └─ boris.blend

Note how all paths have been remapped relative to the placement of 01_01_A.lighting.blend in the root of the output. If we run bam pack /scenes/01-opening/01_01_A.lighting.blend --repo ~/agent327, the output will be different.

~/01_01_A.lighting
   ├─ lib/
   |  └─ chars/
   |     ├─ agent.blend
   |     └─ boris.blend
   └─ scenes
      └─ 01-opening/
         ├─ 01_01_A.lighting.blend  < The BAM packed file
         └─ 01_01_A.anim.blend

In this case no path is remapped, and we simply strip out any file that is not referenced as a direct or indirect dependency of 01_01_A.lighting.blend. This is effectively a sparse copy of the original production tree.

bam remap

Remap blend file paths:

usage: bam remap [-h] {start,finish,reset} ...

This command is a three step process:

  1. First run bam remap start . which stores the current state of your project (recursively).
  2. Then re-arrange the files on the filesystem (rename, relocate).
  3. Finally run bam remap finish to apply the changes, updating the .blend files internal paths.
cd /my/project

bam remap start .
mv photos textures
mv barbershop_v14_library.blend barberhop_libraray.blend
bam remap finish

Note

Remapping creates a file called bam_remap.data in the current directory. You can relocate the entire project to a new location but on executing finish, this file must be accessible from the current directory.

Note

This command depends on files unique contents, take care not to modify the files once remap is started.

Subcommands

remap start

Start remapping the blend files:

usage: bam remap start [-h] [-j] [paths [paths ...]]
-j, --json
Generate JSON output.
remap finish

Finish remapping the blend files:

usage: bam remap finish [-h] [-r] [-d] [-j] [paths [paths ...]]
-r, --force-relative
Make all remapped paths relative (even if they were originally absolute).
-d, --dry-run
Just print output as if the paths are being run.
-j, --json
Generate JSON output.
remap reset

Cancel path remapping:

usage: bam remap reset [-h] [-j]
-j, --json
Generate JSON output.