JohnnyGizmo Color Harmony Tools Documentation

Introduction

The JohnnyGizmo Color Harmony Tools add-on is designed to speed up your color picking workflow in Blender. It generates professional color harmonies based on color theory principles, making it easy to create visually appealing color schemes for materials, lights, and painting workflows.

This tool automatically generates complementary, analogous, triadic, and other color harmony schemes, allowing you to quickly apply these colors to shader nodes, lights, and painting palettes.

Source code is available here.

Installation

Requirements

Installation Steps

  1. Download the extension from the Blender Extensions platform or GitHub
  2. Open Blender and go to Edit → Preferences → Extensions
  3. Click the Install button and select the downloaded extension file
  4. Enable the "JohnnyGizmo Color Harmony" extension
  5. The panels will appear in the Properties panel (Material, Light contexts), Shader Editor sidebar, and 3D View sidebar (when in sculpt/paint modes)

Color Harmony Types

The add-on supports multiple color harmony modes based on color theory:

Complementary

2 Colors: Base color and its direct opposite on the color wheel (180° apart). Creates maximum contrast and visual impact.

Near Complementary

2 Colors: Base color and a color slightly off its direct complementary. Provides high contrast with a bit more subtlety than pure complementary.

Split Complementary

3 Colors: Base color and the two colors adjacent to its direct complementary. Offers high contrast while being more harmonious than pure complementary.

Extended Split Complementary

4 Colors: Base color, its two split complementaries, and the exact complementary. Provides a richer palette with both harmony and contrast.

Analogous

Multiple Colors: Base color and adjacent colors on the color wheel. Creates harmonious, unified color schemes often found in nature.

Accented Analogous

Multiple Colors: An analogous scheme with an added complementary accent color. Combines harmony with a pop of contrast.

Triadic

3 Colors: Three colors equally spaced around the color wheel (120° apart). Creates vibrant, balanced schemes with strong visual interest.

Extended Triadic

4 Colors: A triadic scheme with the addition of a complementary accent. Adds complexity while maintaining balance.

Square

4 Colors: Four colors equally spaced around the color wheel (90° apart). Provides rich, balanced palettes with lots of contrast.

Tetradic (Rectangle)

4 Colors: Two pairs of complementary colors forming a rectangle on the color wheel. Offers the richest possible color combinations.

Monochromatic

Multiple Colors: Variations (tints, shades, and tones) of a single hue. Creates cohesive, elegant designs with subtle variation.

Tint Shade Group

Multiple Colors: Multiple tints (mixed with white), the original color, and multiple shades (mixed with black). Useful for creating value scales and exploring lightness variations.

Achromatic

Multiple Colors: Variations of black, white, and gray (no hue). Perfect for neutral palettes and establishing value relationships.

Material Properties Panel

Access the Color Harmony Tools panel in the Material Properties tab when a material is selected.

Base Color Picker

Select your base color using the color picker. The harmony palette will automatically update based on the selected harmony type and parameters.

Harmony Mode Selector

Choose from the available harmony types using the dropdown menu. Additional parameters (like angle or amount) will appear based on the selected mode.

Generated Palette Display

View the generated color harmony as a visual palette. Click on any color to select it for application to shader nodes.

Apply to Shader Inputs

For materials using Principled BSDF, Emission, or EEVEE Specular shaders, quick-apply buttons allow you to set the selected palette color to various shader inputs:

Principled BSDF

Emission Shader

EEVEE Specular Shader

Copy to Palette

Save the current harmony scheme as a permanent Blender palette for later use or for painting workflows.

Shader Editor Panel

A dedicated panel in the Shader Editor sidebar (N-panel → Color Harmony tab) provides the same functionality as the Material Properties panel, but accessible while working directly in the node editor.

Node Targeting

The panel automatically detects compatible shader nodes (BSDF, Emission, etc.) and allows you to target specific nodes by name. Use the "Get Node" button to automatically select the active node in the shader editor.

Direct Application

Apply harmony colors directly to node inputs without leaving the Shader Editor workspace, streamlining your material creation workflow.

Light Data Properties Panel

When a light object is selected, the Color Harmony Tools panel appears in the Light Properties tab.

Light Color Application

Apply harmony colors directly to light objects:

Get Color from Light

Use the "Get Color" button to sample the current light color and use it as the base for generating a new harmony scheme.

Node Selection

Target specific emission nodes in the light's node tree using the node selector and "Get Node" button.

Palette Panel (Paint/Sculpt Modes)

When in Sculpt, Vertex Paint, or Texture Paint mode, the Harmony Palette panel appears in the 3D View sidebar (N-panel → Harmony Palette tab).

Paint Workflow Integration

Generate color harmonies and save them to Blender's paint palettes for use with painting and sculpting tools.

Copy to Palette

The "Copy To Palette" button creates a new permanent palette with the current harmony colors, automatically naming it with the harmony type and base color values.

Existing Palettes

Access and manage existing paint palettes directly from the panel. Create new palettes or switch between saved harmony schemes.

Direct Color Selection

Click any color in the harmony palette to select it as the active paint color, allowing you to quickly switch between harmonious colors while painting.

API Reference

For developers and advanced users who want to extend or integrate the Color Harmony Tools, here's an overview of the key modules and functions.

Core Modules

color_utils.py

Contains all color theory calculations and conversion utilities. 

# Color space conversions
linear_to_srgb(c)              # Convert linear RGB value to sRGB
srgb_to_linear(c)              # Convert sRGB value to linear RGB
convert_linear_rgb_to_srgb(linear_rgb)
convert_srgb_to_linear_rgb(srgb_rgb)

# Harmony generators (return linear RGB colors)
get_complementary_color(color)           # Returns [base, complementary]
get_near_complementary_colors(color, rad)
get_split_complementary_colors(color)    # Returns [split1, base, split2]
get_analogous_colors(color, count, degrees)
get_triadic_colors(color)
get_square_colors(color)
get_tetradic_colors(color, angle)
get_monochromatic_colors(color, count)
get_achromatic_colors(color, count)
get_tint_shade_group(color, count)

# Utility
get_or_create_palette()        # Get or create "Harmony Palette"

harmony_settings.py

Defines the property group and harmony type enumerations. 

HARMONY_TYPES = [
    ('complementary', "Complementary", "..."),
    ('near_complementary', "Near Complementary", "..."),
    # ... (see full list in Harmony Types section)
]

class HarmonySettings(bpy.types.PropertyGroup):
    mode: EnumProperty(...)           # Selected harmony type
    base_color: FloatVectorProperty(...)  # Base color (RGBA)
    palette: PointerProperty(...)     # Generated palette
    count: IntProperty(...)           # Number of colors
    tetradic_angle: FloatProperty(...)
    analogous_angle: FloatProperty(...)
    near_complementary_angle: FloatProperty(...)
    target_bsdf_node_name: StringProperty(...)

# Access in code:
scene.johnnygizmo_harmony.mode
scene.johnnygizmo_harmony.base_color

Operators

# Apply selected palette color to shader input
JOHNNYGIZMO_COLORHARMONY_OT_ApplySelectedPaletteColor
    .input = "Base Color" | "Emission Color" | etc.
    .obtype = "MESH" | "LIGHT"

# Save current harmony as permanent palette
JOHNNYGIZMO_COLORHARMONY_OT_SavePaletteCopy
    .new_name = "Custom Palette Name"

# Set active palette color
JOHNNYGIZMO_COLORHARMONY_OT_SetActivePaletteColor
    .index = 0  # Color index in palette

# Get selected node
JOHNNYGIZMO_COLORHARMONY_OT_GetSelectedNode

# Get selected palette color
JOHNNYGIZMO_COLORHARMONY_OT_GetSelectedPaletteColor

# Convert palette colors to RGB nodes
JOHNNYGIZMO_COLORHARMONY_OT_PaletteColorToRGBNodes

Usage Examples

Generate Triadic Harmony Programmatically

import bpy
from harmony import color_utils

# Define base color (linear RGB)
base = (0.8, 0.2, 0.1, 1.0)

# Generate triadic colors
triadic_colors = color_utils.get_triadic_colors(base)

# Apply to material
mat = bpy.context.active_object.active_material
if mat and mat.use_nodes:
    bsdf = mat.node_tree.nodes.get("Principled BSDF")
    if bsdf:
        bsdf.inputs["Base Color"].default_value = triadic_colors[0]

Set Base Color and Mode

import bpy

# Access harmony settings
props = bpy.context.scene.johnnygizmo_harmony

# Set base color (linear RGB)
props.base_color = (0.5, 0.3, 0.8, 1.0)

# Set harmony mode
props.mode = 'analogous'

# Adjust parameters
props.count = 5
props.analogous_angle = 0.523599  # 30 degrees in radians

# Palette automatically updates via callback

Access Generated Palette

import bpy

props = bpy.context.scene.johnnygizmo_harmony
palette = props.palette

if palette:
    for i, color in enumerate(palette.colors):
        print(f"Color {i}: RGB({color.color[0]:.3f}, {color.color[1]:.3f}, {color.color[2]:.3f})")

Panel Classes

Library Modules

Tips and Best Practices

Troubleshooting

Panel Not Visible

Colors Not Applying

Palette Display Issues

Version History

Version 1.3.1

Support and Contribution

For bug reports, feature requests, or contributions, please visit the GitHub repository.

Created by Johnny Matthews
License: GPL 2.0 or later