maya-render-setup

maya-render-setup (Pipeline stage)

Typed wrappers around Maya's render setup surfaces. Three surfaces exist and they are not interchangeable:

• renderSetup (maya.app.renderSetup.model.renderSetup) — layers, collections, overrides. Default for new work and the only switching path verified to work.
• legacy render layers (cmds.createRenderLayer / cmds.editRenderLayerGlobals) — pre-2017 renderLayer nodes. Readable always; switching is ignored by Maya in headless sessions, so the tool reports that instead of pretending it worked.
• AOVs — Arnold aiAOV nodes wired into defaultArnoldRenderOptions.aovList. Arnold-specific and fail-closed when the renderer is unavailable.

Layer workflow

1. create_render_layer — name it, set renderable, optionally activate.
2. create_render_collection — populate with members (explicit nodes) or pattern (name glob). Not both.
3. create_render_override — override node.attribute for everything the collection selects. absolute sets a value, relative offsets it, connection wires another attribute.
4. set_current_render_layer — switch layers before rendering.
5. plan_comp_outputs — lay out where the frames should land per layer / AOV.

AOV workflow

1. add_aov — create and wire into aovList. Names are unique.
2. list_aovs — inspect what is connected and its enabled state.
3. set_aov_enabled — skip an AOV for one render without losing it.
4. remove_aov — disconnect and delete when it is genuinely done.

Prefer set_aov_enabled(enabled=false) over remove_aov when the AOV may be needed later: removal deletes the node and cannot be undone.

Arnold prerequisites

Two things catch people out, both verified on Maya 2025:

• defaultArnoldRenderOptions does not exist until an aiOptions node is created. Setting defaultRenderGlobals.currentRenderer to arnold is not enough. The AOV tools create the node when missing.
• aovList reports size == 0 through getAttr(s=True) even when populated, so the next free index comes from listConnections. The contract does this correctly; do not reimplement it.