Skip to content

Add OKLab and Oklch image utilities and nodes, refactor color space nodes#8999

Open
JPPhoto wants to merge 4 commits intoinvoke-ai:mainfrom
JPPhoto:oklab-oklch-support
Open

Add OKLab and Oklch image utilities and nodes, refactor color space nodes#8999
JPPhoto wants to merge 4 commits intoinvoke-ai:mainfrom
JPPhoto:oklab-oklch-support

Conversation

@JPPhoto
Copy link
Copy Markdown
Collaborator

@JPPhoto JPPhoto commented Mar 27, 2026

Summary

Added shared OKLab/OKLCH and related color-conversion utilities, a new unsharp_mask_oklab image node, and a new img_hue_adjust_oklch image node. The PR also consolidates color-conversion logic into the shared backend module, exports the public helpers through invokeai.invocation_api for custom nodes, standardizes public hue contracts to degrees for polar/hue-based spaces, and regenerates frontend API types/schema.

This PR also fixes an existing Oklch blend bug in composition-nodes: main was treating Oklch hue inconsistently and wrapping it like a unit-range value in some blend paths. The refactor standardizes Oklch hue to degrees throughout the shared/public conversion path and updates blend wrapping accordingly, so Oklch blend results may differ slightly from main where the old behavior was incorrect.

Related Issues / Discussions

QA Instructions

  • Run pytest tests/backend/image_util/test_color_conversion.py tests/app/invocations/test_image.py -q

Merge Plan

Checklist

  • The PR has a short but descriptive title, suitable for a changelog
  • Tests added / updated (if applicable)
  • ❗Changes to a redux slice have a corresponding migration
  • Documentation added / updated (if applicable)
  • Updated What's New copy (if doing a release after this PR)

@github-actions github-actions bot added python PRs that change python files invocations PRs that change invocations backend PRs that change backend files frontend PRs that change frontend files python-tests PRs that change python tests labels Mar 27, 2026
@JPPhoto JPPhoto changed the title Add OKLab and Oklch image utilities and nodes Add OKLab and Oklch image utilities and nodes, refactor color space nodes. Mar 28, 2026
@JPPhoto JPPhoto changed the title Add OKLab and Oklch image utilities and nodes, refactor color space nodes. Add OKLab and Oklch image utilities and nodes, refactor color space nodes Mar 28, 2026
@JPPhoto
Copy link
Copy Markdown
Collaborator Author

JPPhoto commented Mar 28, 2026

@dwringer Mind playing with composition nodes here to see if they do what they used to? I made a lot of changes to their internals and fixed what I believe was a bug while I was at it.

@JPPhoto JPPhoto force-pushed the oklab-oklch-support branch from 2f83d75 to e17dbe9 Compare March 29, 2026 01:44
@JPPhoto JPPhoto force-pushed the oklab-oklch-support branch 5 times, most recently from d2b3e32 to 78f82c4 Compare April 6, 2026 12:07
@lstein lstein added the v6.13.x label Apr 7, 2026
@lstein lstein moved this to 6.13.x Theme: MODELS in Invoke - Community Roadmap Apr 7, 2026
@JPPhoto JPPhoto force-pushed the oklab-oklch-support branch 8 times, most recently from 3c5171e to c0a5023 Compare April 10, 2026 11:23
@JPPhoto JPPhoto force-pushed the oklab-oklch-support branch 9 times, most recently from a2f6373 to 02ca0d5 Compare April 19, 2026 01:46
@JPPhoto JPPhoto force-pushed the oklab-oklch-support branch 3 times, most recently from 0d4da3d to 90766fe Compare April 20, 2026 17:22
@dunkeroni
Copy link
Copy Markdown
Collaborator

I have two questions on the conversions portion of this:

  1. Is there a particular reason why we want to handle color conversions on tensor objects instead of image/array-likes?
  2. Would it be cleaner to use/maintain if we included a new python dependency (e.g. Colour) to handle conversions in a standardized way rather than providing custom imports through the invocation_api?

@JPPhoto
Copy link
Copy Markdown
Collaborator Author

JPPhoto commented Apr 20, 2026

I have two questions on the conversions portion of this:

  1. Is there a particular reason why we want to handle color conversions on tensor objects instead of image/array-likes?

The conversions are tensor-based primarily because that matches the rest of the image-processing path here and keeps the code composable with the existing torch-heavy internals. A lot of the current color-space operations in composition.py and the new image nodes are already doing channel-wise math, masking, blending, and gamut handling on tensors, so staying in tensor form avoids repeated conversions between PIL/numpy/tensor representations and keeps the implementation consistent with the surrounding code. It also makes the helpers usable from both built-in nodes and custom nodes that are already working in torch.

  1. Would it be cleaner to use/maintain if we included a new python dependency (e.g. Colour) to handle conversions in a standardized way rather than providing custom imports through the invocation_api?

I considered pulling in a dependency like that, but I decided against it for this change for a few reasons:

  • the scope needed here is fairly small and well-bounded
  • we already have existing custom color-space logic in-tree, so this refactor mostly consolidates and standardizes that rather than introducing an entirely new subsystem
  • adding a new dependency for a narrow set of conversions increases package surface area, maintenance burden, and compatibility risk for custom-node users
  • exposing the helpers through invokeai.invocation_api keeps custom nodes aligned with the same conversion behavior the built-in nodes use, instead of forcing each node author to solve this independently (I can use this in my nodes!)

If this grows further or we start needing a much broader standardized color-management feature set, I think revisiting a dedicated dependency would be reasonable. For this PR, though, keeping it local and consistent with the existing torch-based processing seemed like the lower-risk choice.

@JPPhoto JPPhoto force-pushed the oklab-oklch-support branch 5 times, most recently from e8850b3 to 39fa20e Compare April 21, 2026 01:46
@JPPhoto JPPhoto force-pushed the oklab-oklch-support branch from 39fa20e to c365536 Compare April 21, 2026 01:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

backend PRs that change backend files frontend PRs that change frontend files invocations PRs that change invocations python PRs that change python files python-tests PRs that change python tests v6.13.x

Projects

Status: 6.13.x Theme: MODELS

Development

Successfully merging this pull request may close these issues.

3 participants