Skip to main content
kk1018
Participant
May 5, 2026
Open for Voting

I would like to be able to set the brush color of a paint layer using the Python API.

  • May 5, 2026
  • 0 replies
  • 3 views

## Summary
Please add a Python API to set the active brush color (Base Color and other channels) on Paint Layers.

## Problem
Currently, there is no way to set the brush color of a Paint Layer through the Python API in Substance 3D Painter. The available APIs allow:

- Reading and writing **Fill Layer** uniform colors via `_substance_painter.source.set_source_uniform_color()` and `set_fill_source()`
- Reading and writing **shader parameters** via `alg.shaders.setParameters()` (but this only covers shader-level params like sssColor, not the active brush color)

However, there is no public or private API to set the **active brush's Base Color** that gets applied when painting on a Paint Layer.

## Use Cases
This limitation blocks many useful tools and workflows:

1. **Per-stroke color picker / eyedropper plugins** - Sample colors from the viewport, a reference image, or a baked map (World Space Normal, Position, etc.) and apply them as the brush color for each stroke. This is critical for stylized texturing workflows.

2. **Color palette plugins** - Custom color management UIs that let users build palettes and quickly switch brush colors via shortcuts or buttons.

3. **Procedural color workflows** - Drive brush color from external data sources (CSV files, gradient curves, animation keyframes, etc.).

4. **Tablet/hardware integration** - Bind brush color to physical color picker devices, MIDI controllers, or other input hardware.

5. **Multi-channel synchronized painting** - Paint Base Color, Roughness, and Metallic simultaneously with values derived from a single source.

## Workarounds Attempted (and why they fail)
- Sending keyboard shortcuts (e.g., 'P' for the native eyedropper) via QApplication: unreliable, doesn't allow programmatic color values
- `alg.project.settings.setValue("painting/color", [r,g,b,a])`: writes to a project key-value store but does not affect the brush
- `alg.shaders.setParameters()`: only works for shader-level parameters (sssColor, etc.), not Base Color
- Modifying `PaintLayerNode` properties: no color-related methods exposed
- QML widget manipulation via Qt widget tree: blocked, color picker widgets cannot be modified externally
- Using Fill Layers as proxies: works for fill content, but doesn't translate to actual brush behavior on Paint Layers

## Proposed API
```python
# Pseudocode
import substance_painter.tool

substance_painter.tool.set_brush_color(
    channel_type=ChannelType.BaseColor,
    color=(1.0, 0.5, 0.2)  # RGB 0-1
)

# And/or per-channel
substance_painter.tool.set_brush_value(
    channel_type=ChannelType.Roughness,
    value=0.7
)
```

Alternatively, exposing the existing internal mechanism that the Material panel uses to update brush colors would solve this.

## Impact
This single API addition would unblock an entire category of plugins and significantly extend Painter's scriptability. Many users in the texturing/stylized art community have requested this functionality for years.

Thank you for considering this request.