Render Buddy
User Guide & AOV Reconstruction · v2.4.5 · ApetownArt
Installation, Blender workflow, AOV blend modes, ACES and non-ACES reconstruction in After Effects, Nuke and Fusion.
1. WHAT RENDER BUDDY DOES
Render Buddy is a Blender compositor pipeline builder. It creates and organizes render-pass output nodes, denoised AOVs, Light Group outputs, Puzzlematte masks, motion vectors, separate Optical/Lens FX outputs and a display-transformed Final Image reference. It also provides flexible output naming and optional baked paths for render-farm handoff.
It is designed for artists taking Blender renders into After Effects, Nuke, Fusion and other compositors. It does not replace color management, lighting, render settings or creative compositing decisions.
Terminology:
AOV: Arbitrary Output Variable, an individually useful render pass.
EXR: OpenEXR, a high-dynamic-range image format for compositing.
Beauty: the main rendered image before any separately handled FX.
Final Image: a display-transformed reference, typically JPG or PNG,
using the scene's Blender output settings.
Puzzlematte: a named grayscale mask identifying selected geometry.
2. INSTALLATION
1. Download the Render Buddy ZIP. Keep it zipped.
2. In Blender, open Edit > Preferences > Get Extensions (or Add-ons,
depending on Blender version).
3. Open the menu in that window and choose Install from Disk.
4. Select the Render Buddy ZIP and confirm installation.
5. Enable Render Buddy if Blender asks you to enable the extension.
6. Open a scene and go to Properties > Render (camera icon).
7. Expand the Render Buddy panel.
The current development line targets Blender 5.x, including 5.2. Check the package manifest for its supported Blender minimum version. If upgrading, install the new ZIP and restart Blender if an old copy remains loaded. Avoid keeping duplicate Render Buddy installations.
If the panel is missing, verify the add-on is enabled and check Blender's System Console for registration errors. Save a backup .blend before upgrading an important production project.
3. FIRST RENDER: QUICK START
1. Save your .blend file to a permanent project location.
2. Choose your render engine, camera, resolution and frame range.
3. Open Render Buddy > Output Naming. Review the output template.
4. Open Render Passes. Choose Everything and click Apply (or choose
another preset). A preset changes settings only; it does NOT build.
5. Open Puzzlemattes or Light Groups if you need those exports.
6. In Deliverables & FX, choose the Final Image and any optional FX.
7. Click Build Render Pipeline.
8. Inspect the generated compositor nodes if desired.
9. Render normally: F12 for a frame, Ctrl+F12 for an animation.
10. Open the render output folder and verify the reference image,
AOV EXRs, masks and FX you expected.
IMPORTANT: Rebuild after changing which passes or outputs should exist.
Render Buddy replaces only its own generated nodes; user-created nodes are intended to remain untouched. Save before major pipeline changes.
4. THE INTERFACE
Render Buddy uses accordion sections. Click a header to expand it; opening another section closes the previous one.
OUTPUT NAMING
Output Template: a tokenized path and filename prefix.
Insert Token: adds a supported variable to the template.
Resolved Output Preview: shows the expanded destination.
Apply Resolved Path: updates Blender's output path.
Use Current Output Path: adopts an existing Blender path.
Presets: save, load and delete reusable naming templates.
Frame Padding: frame-number width (for example, 0001).
Create Folders Automatically: create destination directories.
Live Token Resolver: updates paths when relevant scene values change.
RENDER PASSES
Choose a pass preset, click Apply, or adjust pass checkboxes manually.
Relevant Denoise checkboxes appear beside eligible passes.
The presets are:
Everything All standard passes; Light Groups enabled.
Beauty Only Beauty pass.
Glass Only Transmission Color, Direct and Indirect.
Volumes Only Volume Direct and Indirect.
Emissions Only Emission.
Puzzle Matte Only Puzzlemattes and Final Image reference; no
ordinary AOV passes. Create a mask first.
Everything is the default preset. Apply does not rebuild nodes.
Presets also clear irrelevant denoiser checkboxes so the UI matches
the enabled passes. Check the final settings before rendering.
PUZZLEMATTES
Select one or more objects, or select a collection in the Outliner.
Click New Puzzlematte from Selection.
A mask is created, named from the selection and populated for you.
Edit its name, enabled state, invert option and membership as needed.
Add Selected Objects / Add Collection: extend an existing mask.
Remove Selected Entry: remove membership from the current mask.
Remove Selected Mask: delete a mask definition.
Enable Export and choose the relevant EXR/AA/denoise options.
These are grayscale ID masks, NOT full Cryptomatte metadata.
For predictable results, avoid overlapping mask memberships; a
single object should not be assigned to competing masks.
LIGHT GROUPS
Light Groups are per View Layer and depend on Cycles support.
Select one or several light objects.
Click Make Light Group. A single light uses its name; multiple
selected lights prompt you to enter a group name.
Click Refresh if the list does not immediately reflect a change.
Enable the groups you want to export. Optional Light Group denoising
can be configured separately.
Remove Light Group opens a chooser and removes the selected group;
verify the intended group before confirming.
Creating groups does not by itself rebuild the compositor: click
Build Render Pipeline when ready.
DENOISING
Controls overall denoiser generation, HDR denoising and whether
undenoised/raw pass outputs are retained. Denoising can lose fine
texture or cause temporal flicker; test animation frames.
COMPOSITOR OUTPUT
Select Multilayer EXR or Separate EXRs, Viewer node creation and
automatic node layout. Multilayer EXR packages passes together;
Separate EXRs are convenient for targeted downstream imports.
EXR SETTINGS
Configure EXR compression and precision by output category.
Sensible defaults include half-float DWAA for many image passes,
lossless ZIP for masks and full 32-bit float ZIP for motion vectors.
Avoid lossy compression for ID masks and data passes.
DELIVERABLES & FX
Final Image: saves a display-transformed reference using Blender's
output settings, distinct from scene-linear EXR working data.
Composite Layers EXR: layered EXR for downstream compositing.
Optical FX: separately exported bloom, fog glow, streaks and sun
beams, when enabled and built into the FX chain.
Lens FX: separately exported distortion, chromatic aberration and
defocus, when enabled and supported by the scene setup.
Motion Vectors: exports motion information for post-production.
FX output depends on the enabled nodes/settings and available data.
BOTTOM ACTIONS
Build Render Pipeline: creates/rebuilds Render Buddy output nodes.
Bake Token Paths: freezes resolved output paths for farm handoff.
Unbake Token Paths: restores the saved pre-bake paths/settings.
5. OUTPUT PATHS, TOKENS AND ANIMATION NAMING
Default template:
$blenddir/renders/$camera/$prj_$camera_$fps_$res_
For example, a saved project MaterialTester1.blend, camera Main_Camera, 30 fps and 2560x1920 resolution might resolve to a prefix similar to:
.../renders/Main_Camera/MaterialTester1_Main_Camera_30_2560x1920_
The final underscore matters for sequences. With four-digit padding:
MaterialTester1_Main_Camera_30_2560x1920_0001.jpg
MaterialTester1_Main_Camera_30_2560x1920_0002.jpg
Useful tokens include:
$blenddir Folder containing the .blend file
$prj Project/blend filename
$scene Scene name
$camera Active camera name
$viewlayer Active view-layer name
$engine Render engine
$fps Frames per second
$res Render resolution
$frame Frame number
$frame4 Four-digit frame number
$date Current date
$up1 etc. Parent-folder references
Use the Insert Token menu for the full supported set. Preview the expanded path before a long render. Avoid characters forbidden by your operating system and keep project/camera names reasonably short.
Typical output folders are named by pass, for example:
Diffuse_Color_Denoised/
Glossy_Indirect_Denoised/
Transmission_Direct_Denoised/
Puzzlemattes/
MotionVectors/
The FILES inside pass folders retain their descriptive project/prefix and pass naming. Puzzlemattes and MotionVectors folders should not receive the full project/camera prefix in v2.4.5.
For animation, verify that frame numbers are padded and unique, that file extensions match the chosen format, and that a short test range produces consecutive frames. Do not rely on a movie container for compositing interchange: use image sequences.
6. BAKING PATHS FOR A RENDER FARM
Live token resolution is convenient on your workstation, but an unmodified farm worker may not have Render Buddy installed.
Recommended handoff:
1. Save the .blend file inside the project you intend to submit.
2. Finalize output settings and Build Render Pipeline.
3. Click Bake Token Paths.
4. Save the .blend file again AFTER baking.
5. Check that paths are Blender-relative (//...) and that the farm
receives the project folder and required linked assets.
6. Test a single frame on a machine/worker without the add-on.
7. Submit the animation range.
Baking freezes paths and disables the live resolver. For Puzzlemattes, it also stores the required Object Index assignments in the .blend so workers do not need Render Buddy's render handlers. Unbake restores the saved pre-bake state, including original indices where available.
IMPORTANT: Relative paths are relative to the .blend location. Moving
only the .blend file without its expected directory structure can break outputs. A farm may have its own output-path remapping rules. Verify those rules and test before a large submission.
If you change cameras, output tokens, mask membership or pass selection after baking, unbake, rebuild as needed, bake again and save.
7. AOVS: WHAT THEY ARE FOR
Beauty:
Reference for comparing your reconstruction or grade to Blender.
Diffuse Color / Direct / Indirect:
Base color and lighting contributions for diffuse surfaces. Color
and lighting components are not all meant to be added blindly.
Glossy Color / Direct / Indirect:
Specular/reflection color and illumination components.
Transmission Color / Direct / Indirect:
Refracted/transmitted contributions, especially glass and liquids.
Volume Direct / Indirect:
Light scattered through volumetric media.
Emission:
Emissive contribution; useful for selective glow treatments.
Environment:
World/background contribution where available.
Ambient Occlusion:
A utility/shading pass, not necessarily a physically separate light
term to add at full strength to a beauty reconstruction.
Shadow:
Utility for grading or integration; its interpretation depends on
the render pass and compositing operation.
Light Groups:
Isolated lighting contributions that may allow relighting in comp.
They are not arbitrary additive duplicates of an already complete
beauty. Validate reconstruction with your actual Cycles setup.
Puzzlemattes:
Black/white selections for isolating objects or collections.
Treat as data masks; never apply a display transform to mask values.
Motion Vectors:
Pixel-motion data for vector blur and certain temporal operations.
Do not treat as RGB artwork; vector conventions vary by compositor.
8. INDUSTRY COLOR-MANAGEMENT PRINCIPLES
THE MOST IMPORTANT RULE:
Keep EXR compositing data scene-linear, and apply the intended
display/view transform only for viewing or final delivery.
A common ACES workflow uses scene-linear ACEScg for CG working data, with the correct input conversion from Blender's actual EXR color space. Do NOT simply label every Blender EXR 'ACEScg'. Blender can output different spaces depending on the OCIO configuration and setup. Confirm the project's color configuration and EXR encoding first.
A reliable workflow:
1. Agree on an OCIO configuration and working space before rendering.
2. Record Blender's display, view, look, exposure and gamma settings.
3. Export linear EXRs for compositing and a display-transformed Final
Image for visual comparison.
4. Interpret each EXR in its actual source color space, then convert
to the compositor's linear working space if necessary.
5. Composite light/CG contributions in linear light, not gamma-encoded
display space.
6. Apply the correct view/output transform once for monitoring or
delivery. Avoid double-transforming the Final Image reference.
7. Compare the comp against Blender's reference with matched viewing
transforms and exposure.
Half-float EXR is generally sufficient for image passes; 32-bit float is useful for demanding data such as vectors. ZIP is lossless; DWAA is lossy and can be acceptable for many beauty/light outputs but should not be the default for IDs, precise masks or motion data.
Premultiplication matters: when combining CG with live-action, ensure alpha is interpreted consistently. For grading operations that should not darken edges, unpremultiply before the operation and premultiply afterward, when appropriate. Do not unpremultiply pure data passes.
9. NUKE: RECOMMENDED COMPOSITING WORKFLOW
Nuke is a strong choice for deep, multilayer EXR and linear-light CG reconstruction.
1. Set the project OCIO configuration and working/view spaces to match
the production. Check that Nuke reads Blender EXRs correctly.
2. Read the multilayer EXR or individual EXR sequences with Read nodes.
3. Inspect channels using Shuffle / Shuffle2. Confirm names and
channels before wiring the comp.
4. Read the display-transformed Final Image as a REFERENCE, not as an
additional linear-light contribution.
5. For a diffuse reconstruction, the typical Cycles relation is:
diffuse = diffuse_color * (diffuse_direct + diffuse_indirect)
Likewise, a common glossy/transmission relation uses the relevant
color pass multiplied by its direct + indirect lighting. However,
exact pass semantics vary with engine and settings: validate against
the Beauty, rather than assuming a universal formula.
6. Combine independent reconstructed contributions with Merge (plus)
in linear light. Include emission, environment and volume only as
appropriate for the pass definitions. Do not add Beauty on top.
7. Compare reconstruction to Beauty using a Difference or Merge
(difference) view; small differences can occur with denoising,
transparency, effects or omitted components.
8. For Light Groups, isolate and grade lighting contributions with
Grade/ColorCorrect nodes, then recombine according to the actual
light-group output semantics. Test against Beauty.
9. For Puzzlemattes, Read the mask EXR, Shuffle its mask channel into
alpha/mask input, then use it to drive Grade, ColorCorrect or Merge.
Set mask interpretation to raw/data, not a display color space.
10. Use separate Optical FX as a controlled overlay, often with plus or
screen-like treatment depending on what the pass actually contains.
Inspect alpha and black levels first; avoid doubling effects already
present in the Beauty/Final reference.
11. For motion vectors, check the vector channels, coordinate direction
and scaling before using VectorBlur. Test on moving edges.
12. Render a short EXR comp range, inspect edge quality and temporal
stability, then output the requested delivery color space/format.
Suggested node organization:
READS -> CHANNEL EXTRACTION -> RECONSTRUCTION -> RELIGHT/GRADE
-> MASKS -> OPTICAL/LENS FX -> VIEW/OUTPUT TRANSFORM -> WRITE
For lens distortion, prefer a consistent undistort/comp/redistort workflow when integrating with plates. Distortion and defocus are not always safely treated as simple additive overlays.
10. AFTER EFFECTS: RECOMMENDED COMPOSITING WORKFLOW
After Effects can composite EXR sequences, but channel extraction and OCIO setup deserve extra attention.
1. Create a project and set color management deliberately. For an
ACES-based workflow, use a supported OCIO configuration/working
space if available in your AE version and pipeline.
2. Import EXR sequences as sequences, not hundreds of stills. Verify
frame rate, start frame and duration.
3. Use EXtractoR or another compatible EXR channel extraction method
for multilayer files; for Separate EXRs, import the needed passes.
Plugin availability and channel naming vary by AE version.
4. Confirm that source footage is interpreted in the correct color
space. Do not automatically apply an sRGB conversion to linear EXRs.
5. Use a 32-bpc project for HDR compositing and linear-light math.
6. Keep a copy of the Blender Final Image as a reference layer, disabled
during reconstruction and not added to the light passes.
7. Reconstruct contributions with the proper math: multiply color by
direct+indirect illumination where required; then add independent
contributions in linear light. AE blending modes such as Add and
Multiply can help, but use explicit calculations where precision
matters and verify against Beauty.
8. Import Puzzlematte EXRs as linear data. Use Set Matte, Track Matte or
an equivalent mask extraction workflow; do not color-transform masks.
9. Treat Optical FX as separate controlled layers. Add/Screen may be
useful for light-only effects, but verify the FX pass's alpha and
whether it already contains part of the underlying image.
10. Motion vector workflows in AE depend on the effect/plugin. Blender
vector data is not automatically compatible with every motion-blur
plugin; confirm channel order, sign and units.
11. Check transparency/premultiplication. Dark or bright halos around
edges usually signal a premult/interpretation mismatch.
12. Render a short preview range, compare to Blender's reference, then
export to the agreed delivery color space.
AE PRACTICAL TIP:
If your pipeline does not reliably read all multilayer EXR channels,
use Render Buddy's Separate EXRs mode. It is often simpler to audit,
version and troubleshoot. Keep file sequences together and maintain
identical frame numbers across passes.
11. FUSION / DAVINCI RESOLVE WORKFLOW
1. Configure Fusion/Resolve color management or OCIO to match the
Blender source space and intended working space.
2. Load EXR sequences through Loader/MediaIn. Inspect available
channels for multilayer files, or import separate passes.
3. Use ChannelBooleans, CustomTool or equivalent nodes for explicit
pass multiplication and addition. Validate against Beauty.
4. Use bitmap/mask nodes to consume Puzzlematte grayscale data.
5. Use color correction on selected Light Group contributions before
recombining, with matched color spaces.
6. Treat FX and vector passes according to their data semantics; test
alpha and vector conventions rather than assuming interchangeability.
7. Keep the view transform separate from scene-linear calculations and
use the correct output transform on delivery.
12. AOV RECONSTRUCTION: BLEND MODE QUICK-REFERENCE KEY
This section is the practical companion to the Nuke, After Effects and Fusion instructions above. It is designed for Cycles-style AOVs and must be checked against the actual pass definitions in your render.
THE THREE MOST IMPORTANT OPERATIONS
ADD / PLUS: Sum independent linear-light contributions.
MULTIPLY: Multiply a material-color pass by its light result.
MASK / MATTE: Use the pass as a selection, not visible RGB light.
EXAMPLE: BASIC RECONSTRUCTION
Diffuse = Diffuse_Color * (Diffuse_Direct + Diffuse_Indirect)
Glossy = Glossy_Color * (Glossy_Direct + Glossy_Indirect)
Transmission= Transmission_Color *
(Transmission_Direct + Transmission_Indirect)
Rebuilt image (starting point) =
Diffuse + Glossy + Transmission + Emission + Environment
+ other independent contributions where applicable.
IMPORTANT: Do not add the Beauty pass to this reconstruction.
IMPORTANT: The Volume Direct/Indirect passes and Environment pass
must be checked for their actual Cycles semantics. Some components
may already be included or require special treatment. Do not assume
adding every exported pass recreates Beauty exactly.
IMPORTANT: If the rendered output includes transparency, denoising,
subsurface, alpha handling or compositing effects, differences may
remain even when the light math is correct.
AOV BLEND MODE QUICK REFERENCE
| Pass | Blend mode / action | How to use it |
|---|
| Beauty / Beauty_Denoised | Normal | Reference or starting plate, not added to reconstructed beauty |
| Diffuse_Direct | Add | Add to Diffuse_Indirect |
| Diffuse_Indirect | Add | Add to Diffuse_Direct |
| Diffuse_Color | Multiply | Multiply the combined Diffuse lighting |
| Glossy_Direct | Add | Add to Glossy_Indirect |
| Glossy_Indirect | Add | Add to Glossy_Direct |
| Glossy_Color | Multiply | Multiply the combined Glossy lighting |
| Transmission_Direct | Add | Add to Transmission_Indirect |
| Transmission_Indirect | Add | Add to Transmission_Direct |
| Transmission_Color | Multiply | Multiply combined Transmission lighting |
| Emission | Add / Plus | Independent emissive contribution |
| Environment | Conditional | Check against Beauty; avoid double-counting |
| Volume_Direct / Indirect | Conditional | Check against Beauty and render settings |
| Ambient_Occlusion | Utility | Optional artistic Multiply, not a default beauty term |
| Shadow | Utility | Not a universal Add pass |
| LightGroup_<name> | Relighting | May replace an existing lighting contribution |
| Puzzlemattes | Matte | Use as masks, never add to RGB |
| MotionVectors | Data | Use for vector blur, never add to RGB |
| OpticalFX | Conditional | Add only if the export is a clean additive FX delta |
| LensFX | Effect-specific | Distortion and defocus cannot generally be reconstructed by Add |
| Final Image (JPG/PNG) | Reference | Display-transformed; not a linear AOV |
DENOISED VERSIONS
A denoised pass follows the SAME blend math as its original.
Prefer a consistent set of denoised passes when rebuilding a
denoised Beauty. Mixing denoised and noisy passes can create seams,
inconsistent grain and temporal flicker.
ONE-MINUTE CHECK
1. Start with the three reconstructed material contributions.
2. Add only independent light terms one at a time.
3. Compare to Beauty in the same linear working space.
4. Use a Difference view; inspect highlights and transparent edges.
5. Keep the display transform OFF the working pixels and ON the view.
13. AFTER EFFECTS: LAYER STACK AND BLEND MODES
Use a 32-bpc project and linear-light calculations. Extract individual channels from multilayer EXRs or import Render Buddy's Separate EXRs.
A beginner-friendly reconstruction uses PRECOMPS:
PRECOMP: DIFFUSE_LIGHT
Diffuse_Direct Normal (base layer)
Diffuse_Indirect Add (above Direct)
PRECOMP: DIFFUSE_RESULT
DIFFUSE_LIGHT Normal (base layer)
Diffuse_Color Multiply (above light precomp)
PRECOMP: GLOSSY_LIGHT
Glossy_Direct Normal (base layer)
Glossy_Indirect Add (above Direct)
PRECOMP: GLOSSY_RESULT
GLOSSY_LIGHT Normal (base layer)
Glossy_Color Multiply (above light precomp)
PRECOMP: TRANSMISSION_LIGHT
Transmission_Direct Normal (base layer)
Transmission_Indirect Add (above Direct)
PRECOMP: TRANSMISSION_RESULT
TRANSMISSION_LIGHT Normal (base layer)
Transmission_Color Multiply (above light precomp)
MASTER REBUILD (BOTTOM TO TOP)
DIFFUSE_RESULT Normal (base)
GLOSSY_RESULT Add
TRANSMISSION_RESULT Add
Emission Add
Environment Conditional Add, after comparison
Volume contributions Conditional Add, after comparison
REFERENCE IMAGE Separate comparison layer, NOT Add
PUZZLEMATTE Set Matte / Track Matte, NOT visible RGB
MOTION VECTORS Data input to compatible effect, NOT visible
AE NOTES
* Set precomp backgrounds to transparent black. Check that layer
opacity is 100%, effects do not clamp HDR, and blending occurs in
linear light. For rigorous reconstruction, use explicit arithmetic
effects or expressions if the blend result is ambiguous.
* Add means addition. Screen is NOT the same as Add and is generally
not the right choice for physically additive AOV reconstruction.
* Treat AOV EXRs as the source linear color space, not automatically
as sRGB. In a color-managed project, ensure interpretation does not
accidentally transform raw passes twice.
* AE may show different channel labels or alpha behavior depending
on the EXR importer. Confirm that color and lighting passes are
extracted as expected and avoid accidental alpha multiplication.
14. NUKE: NODE GRAPH AND MERGE OPERATIONS
Nuke's Merge node makes the arithmetic explicit:
DIFFUSE
Shuffle Diffuse_Direct --+
Merge(plus) -> Merge(multiply) -> Diffuse
Shuffle Diffuse_Indirect-+ ^
|
Shuffle Diffuse_Color
GLOSSY
Glossy_Direct + Glossy_Indirect -> Merge(plus)
subtotal * Glossy_Color -> Merge(multiply)
TRANSMISSION
Transmission_Direct + Transmission_Indirect -> Merge(plus)
subtotal * Transmission_Color -> Merge(multiply)
MASTER
Diffuse + Glossy -> Merge(plus)
+ Transmission -> Merge(plus)
+ Emission -> Merge(plus)
+ other validated contributions-> Merge(plus)
NUKE PASS-TO-OPERATION KEY
Color x Lighting Merge(multiply)
Independent light Merge(plus)
Puzzlematte Shuffle to mask input; not Merge(plus)
Light Group Grade/ColorCorrect then validated recombination
Motion vectors VectorBlur input, after channel/unit verification
Final Image Viewer comparison, never part of rebuild
Use a Difference operation to compare your reconstruction to the Beauty pass. Watch out for Merge bounding-box, alpha and premultipli- cation behavior. If you are comparing denoised outputs, compare like with like and account for differences in denoising methods.
15. FUSION / DAVINCI RESOLVE: NODE AND MERGE OPERATIONS
Fusion's Merge tool is principally an OVER/compositing tool. Do not assume that a default Merge node is the equivalent of Nuke Merge(plus). For exact AOV arithmetic, ChannelBooleans or CustomTool expressions are often clearer and more predictable.
DIFFUSE LIGHT:
CustomTool / ChannelBooleans: Direct + Indirect
DIFFUSE RESULT:
CustomTool / ChannelBooleans: Color * DiffuseLight
GLOSSY RESULT:
(Glossy_Direct + Glossy_Indirect) * Glossy_Color
TRANSMISSION RESULT:
(Transmission_Direct + Transmission_Indirect)
* Transmission_Color
MASTER:
DiffuseResult + GlossyResult + TransmissionResult + Emission
+ any other verified independent contributions
Puzzlemattes -> Bitmap / effect mask input, not visible RGB.
Light Groups -> Grade/ColorCorrect, then verify light-group math.
Motion Vectors -> vector-aware tool with verified channel layout.
Optical/Lens FX -> inspect output semantics before blending.
In Fusion, use explicit arithmetic in linear light, then a color- managed Viewer and correct final output transform. Check alpha and clamping when mixing different tools.
16. ACES AND NON-ACES: TWO COMPLETE COLOR WORKFLOWS
The AOV BLEND MATH above does not change between ACES and non-ACES. What changes is how source EXR values are interpreted, the working space and the transform used for viewing/delivery.
WORKFLOW A: ACES / ACEScg -----------------------------------------------------------------------
1. In Blender, confirm the exact OCIO configuration, render working
space and EXR output encoding. Do not infer ACEScg from a filename.
2. Import the EXR as its ACTUAL source space. If the EXR is not ACEScg,
convert it once into linear ACEScg (AP1) before AOV reconstruction.
3. Perform all Add and Multiply operations in scene-linear ACEScg.
4. Treat Puzzlemattes, IDs and motion vectors as RAW DATA: no ACES
color-space conversion or display transform.
5. Monitor using the production ACES display/view transform, selected
for the actual display and target look. Do not bake the view transform
into the working AOVs.
6. Compare the rebuilt comp to Blender Beauty with equivalent source
interpretation and viewing transforms. A display-transformed JPG
is useful as a visual reference but not a pixel-identical linear
comparison source.
7. Deliver scene-linear EXR in the requested working/delivery space,
or apply the specified ACES output transform ONCE for display files.
EXAMPLE
Source EXR is linear Rec.709/sRGB primaries -> OCIO convert to ACEScg
-> Add/Multiply reconstruction -> ACES view/output transform -> JPG.
If source EXR already is ACEScg, SKIP the source-to-ACEScg conversion.
WORKFLOW B: NON-ACES / STANDARD SCENE-LINEAR
1. Determine the source EXR's actual linear color space, often a
scene-linear space using Rec.709/sRGB primaries in a standard Blender
setup. Verify this in Blender's configuration rather than guessing.
2. Set the compositor working space to that same linear space, or
convert once into another agreed scene-linear working space.
3. Add and Multiply passes in linear light, NOT in display-referred
sRGB gamma-encoded values.
4. Treat Puzzlemattes, IDs and motion vectors as RAW DATA.
5. For a standard SDR delivery, apply the agreed display conversion
(for example, linear Rec.709/sRGB primaries -> display sRGB) once.
If the Blender reference uses AgX or another view transform, simple
sRGB conversion will NOT visually match it; use the same Blender
OCIO view transform when a match is required.
6. Keep EXR masters linear and display deliveries display-referred.
EXAMPLE
Source EXR linear Rec.709/sRGB primaries -> linear reconstruction
-> Blender AgX view (if matching Blender reference) -> SDR delivery.
APPLICATION CHECKLIST
After Effects: 32 bpc; linear working operations; appropriate OCIO
input/view/output management for the chosen pipeline. Do not apply
a second sRGB conversion to a display-transformed reference.
Nuke: project OCIO; Read node input space; linear working space;
Viewer Process for display; Write output transform as specified.
Fusion: project/OCIO input and working spaces; linear CustomTool or
ChannelBooleans operations; managed viewer and delivery transform.
COMMON COLOR FAILURES
Too bright: adding Beauty plus AOVs; wrong Plus math; double view
transform; an FX pass contains a full underlying image.
Too dark: multiplying the wrong passes; treating linear EXR as
gamma-encoded or interpreting source color space incorrectly.
Washed out: missing view transform or inappropriate display mapping.
Wrong saturation/hues: assigning ACEScg to a non-ACEScg source EXR.
Mask fringes: alpha premultiplication mismatch or color transforms
applied to a grayscale data mask.
17. OPTIONAL FX, MASKS AND LIGHT GROUPS: WHAT NOT TO ADD
OPTICAL FX
A separate glow/streak overlay can often be composited with Add
if it truly contains ONLY the incremental light contribution. If the
exported layer includes the source image, adding it duplicates the
beauty. Screen is an artistic alternative, not an exact rebuild.
LENS FX
Distortion, defocus and chromatic aberration generally transform
the image; they are not independent light-energy terms. Recreate
the operation in the compositor or use the exported result with
correct replacement/matte logic. Do not blindly Add a LensFX EXR.
LIGHT GROUPS
Light-group outputs can be used for controlled relighting. Whether
to add, replace or subtract a group depends on how the group passes
were exported and whether their contribution is already in Beauty.
First verify the group reconstruction with a difference check.
PUZZLEMATTES
Black = 0, white = 1, gray = partial coverage. Use to isolate
corrections, not to brighten the beauty. Keep the mask raw/linear.
AMBIENT OCCLUSION AND SHADOW
AO can be used as an artistic Multiply treatment but may double
darken physically correct beauty lighting. Shadow is a utility pass
whose correct use depends on its definition; it is not always a
straightforward additive contribution.
18. RECOMMENDED PRODUCTION CHECKLIST
Before rendering:
[ ] Save the .blend and verify the active camera / View Layer.
[ ] Confirm engine, resolution, FPS, frame range and sample quality.
[ ] Choose a pass preset, click Apply, then inspect enabled passes.
[ ] Configure Puzzlemattes and Light Groups if needed.
[ ] Check EXR precision/compression and denoiser choices.
[ ] Confirm the output preview and trailing filename separator.
[ ] Build Render Pipeline.
[ ] Test a frame and inspect actual EXR channels and folder names.
[ ] Test at least a few frames of an animation for stable masks/FX.
For farm submission:
[ ] Bake paths, save the .blend and submit linked dependencies.
[ ] Test on a worker without Render Buddy installed.
[ ] Verify no literal unresolved token names appear in output paths.
For compositing:
[ ] Match OCIO/working spaces and frame rate.
[ ] Treat EXR as linear working data, reference JPG/PNG as display data.
[ ] Reconstruct and difference-check against Beauty.
[ ] Avoid mixing denoised and raw components unintentionally.
[ ] Confirm alpha, masks, vectors and FX blending semantics.
[ ] Deliver the specified display/output transform only once.
19. TROUBLESHOOTING
No output or missing pass folder:
Check that the pass is enabled, the preset was Applied, the pipeline
was Built and the scene rendered. Confirm folder permissions.
Preset changed but output nodes did not change:
This is expected. Click Build Render Pipeline after Apply.
Puzzlematte is black:
Confirm mask export is enabled, targets are assigned, the right View
Layer is rendered and the generated ID Mask nodes are connected.
Test with a simple cube before debugging a complex scene.
Light Group missing:
Confirm Cycles and the active View Layer, assign light objects using
Make Light Group, click Refresh, enable export and rebuild.
Unexpected filenames or full-name mask/vector folders:
Confirm v2.4.5 is installed. Rebuild the pipeline. If paths were
baked previously, Unbake first and Bake again after rebuilding.
Animation frame numbers touch the prefix:
Include a trailing underscore in the template, for example $res_.
Check the resolved output preview and test frames 0001-0003.
Farm outputs literal tokens or writes to unexpected folders:
Bake paths, save the .blend and verify the submitted file is the
baked version. Test the relative paths on the worker.
Comp is brighter than Beauty:
You may have added Beauty to AOVs, counted a contribution twice,
used an incorrect pass reconstruction or applied a color transform
twice. Compare individual contributions in linear space.
Comp is too dark or has odd color:
Verify EXR source color space, OCIO configuration, view transform,
alpha handling and whether color passes need multiplication.
Mask edges have halos:
Keep masks as data, inspect filtering/AA, and check premultiplication
and whether denoising is appropriate for that mask.
FX appear twice:
Check whether the Final Image already contains those effects. Do not
add separate FX on top of a reference that includes the same FX.
20. LIMITATIONS AND NOTES
- Render Buddy builds a compositor pipeline; it does not guarantee a
one-size-fits-all beauty reconstruction across Blender versions.
- Puzzlemattes are ID-based grayscale masks, not Cryptomatte files.
- Light Groups depend on the active View Layer and supported engine.
- FX overlays and motion vectors require verification in the target
compositor; conventions are not identical across applications.
- Denoising may change the relationship between raw passes and Beauty.
- File Output node APIs differ between Blender versions.
- User-created compositor nodes should be preserved, but always keep
scene backups before upgrading or rebuilding production projects.
- Render Buddy is actively developed. Report reproducible bugs with
Blender version, Render Buddy version, a screenshot and steps.
21. SUGGESTED LEARNING EXERCISES
EXERCISE A: SIMPLE BEAUTY + MASK
Render a cube and sphere. Select the sphere, create a Puzzlematte,
choose Puzzle Matte Only, Apply, Build and render. In Nuke or AE,
use the mask to grade only the sphere.
EXERCISE B: GLASS
Render a glass object with a contrasting background. Choose Glass
Only, Apply and Build. Compare Transmission Color/Direct/Indirect
against Beauty. Observe refraction and denoising differences.
EXERCISE C: LIGHT GROUP RELIGHT
Create key and rim lights. Make separate Light Groups, enable export,
Build and render. Grade their contributions independently in Nuke or
Fusion. Verify the recombination against Beauty.
EXERCISE D: FARM HANDOFF
Create a three-frame test, Build, Bake, save and render the file on a
second Blender installation without Render Buddy. Check every path.
22. RELEASE 2.4.5: INSTALLATION, PERMISSIONS & SUPPORT
Render Buddy v2.4.5 is a packaging and diagnostics update prepared for Superhive review. The compositor workflow and render outputs remain as documented in the earlier sections.
OFFICIAL DOCUMENTATION & SUPPORT
Documentation and support page: https://apetownart.com/SofwareGuides/Render_Buddy_Guide.html. This is the same website listed in the Blender extension manifest. If a page is unavailable, confirm the URL is published on your hosting service before distributing the add-on.
EXTENSION MANIFEST & FILE ACCESS
The manifest uses schema_version = "1.0.0" and identifies add-on version 2.4.5. The extension declares file access because it creates output directories, saves rendered images and EXRs, stores presets and may write diagnostic logs when enabled.
DIAGNOSTIC LOGGING: OFF BY DEFAULT
File-based diagnostics are optional. To enable them, open Blender Preferences, find the Render Buddy extension/add-on preferences and enable Enable Diagnostic File Logging. Console diagnostics remain available independently of this setting. The file render_buddy_debug.log is stored under Blender's user configuration in the render_buddy directory and capped at approximately 1 MiB by retaining recent entries. Disable the preference when troubleshooting is finished.
LICENSING AND PACKAGE CONTENTS
The release includes a GPL-3.0-or-later license file and copyright attribution to 2026 ApetownArt. The submission ZIP excludes test sources, unused duplicate icon files and the old v1.6.5 README. The included README documents v2.4.5 installation and usage.
VERSION 2.4.5 CHECKLIST
- Install the new ZIP and confirm the extension loads in Blender.
- Open Render Properties and confirm Render Buddy panels and presets display.
- Build a pipeline and render a short frame range; inspect EXR and mask outputs.
- Check that no diagnostic log grows by default; enable logging only for a test.
- Verify the documentation link resolves publicly before Superhive resubmission.
Roadmap note: 3D Data Bridge / baked camera and object tracking-data export to After Effects, Nuke and Fusion is a planned future feature and is not included in v2.4.5.
Render Buddy v2.4.5 · ApetownArt · Documentation and support: Render Buddy Guide