{"record":{"id":"126410f81d09dc1a","repo":"Intervention/image","slug":"failed-to-import-color-color-class-to-colorspac-126410","errorCode":null,"errorMessage":"Failed to import color {color_class} to {colorspace_class}","messagePattern":"Failed to import color (.+?) to (.+?)","errorType":"exception","errorClass":"Intervention\\Image\\Exceptions\\ColorException","httpStatus":null,"severity":"error","filePath":"src/Colors/Oklch/Colorspace.php","lineNumber":112,"sourceCode":"\n    /**\n     * Import given OKLAB color OKLCH colorspace.\n     *\n     * @throws ColorException\n     */\n    private function importOklabColor(OklabColor $color): OklchColor\n    {\n        $a = $color->a()->value();\n        $b = $color->b()->value();\n\n        $c = sqrt($a * $a + $b * $b);\n        $h = rad2deg(atan2($b, $a));\n        $h = $h < 0 ? $h + 360 : $h;\n\n        try {\n            return new Color($color->lightness()->value(), $c, $h, $color->alpha()->normalized());\n        } catch (InvalidArgumentException $e) {\n            throw new ColorException(\n                'Failed to import color ' . $color::class . ' to ' . $this::class,\n                previous: $e,\n            );\n        }\n    }\n\n    /**\n     * Import given RGB color to OKLCH color space.\n     *\n     * @throws ColorException\n     */\n    private function importRgbColor(RgbColor $color): OklchColor\n    {\n        try {\n            $color = $color->toColorspace(Oklab::class);\n        } catch (InvalidArgumentException $e) {\n            throw new ColorException(\n                'Failed to import color ' . $color::class . ' to ' . $this::class,","sourceCodeStart":94,"sourceCodeEnd":130,"githubUrl":"https://github.com/Intervention/image/blob/5598b9e39751c34afc5cdee84abef77f92c26f68/src/Colors/Oklch/Colorspace.php#L94-L130","documentation":"Converting OKLAB to OKLCH computes chroma as c = sqrt(a^2 + b^2) and hue via atan2, then constructs an OklchColor (src/Colors/Oklch/Colorspace.php:100-117). The Chroma channel is capped at 0.4, but two valid OKLAB axes of up to 0.4 each yield c up to ~0.566, so corner values overflow the chroma range and the wrapped construction throws ColorException. This is the one 'Failed to import' path that genuinely fires with valid input.","triggerScenarios":"$oklab->toColorspace(Oklch\\Colorspace::class) where a and b are both large, e.g. new Oklab\\Color(0.5, 0.4, 0.4) gives chroma 0.5657 > 0.4. Also fires when the source lightness/alpha channels are corrupt (out of their own bounds).","commonSituations":"Converting saturated out-of-sRGB-gamut OKLAB colors (typical when generating wide-gamut palettes or interpolating in OKLab) to OKLCH for display; palette->toColorspace() over mixed colors hitting an extreme corner.","solutions":["Pre-check the chroma before converting: sqrt(a*a + b*b) must be <= 0.4","Clamp or scale the a/b axes down before conversion to bring chroma within range","Catch ColorException and treat the color as out of gamut (keep it in OKLAB or clamp to max chroma)","If the source lightness/alpha are corrupt, rebuild the color via Oklab\\Color::create() first"],"exampleFix":"// before\n$oklch = new Oklab\\Color(0.5, 0.4, 0.4)->toColorspace(Oklch\\Colorspace::class); // c=0.566 > 0.4 -> ColorException\n\n// after\n$scale = 0.4 / sqrt(0.4**2 + 0.4**2);\n$oklab = new Oklab\\Color(0.5, 0.4 * $scale, 0.4 * $scale); // chroma now exactly 0.4\n$oklch = $oklab->toColorspace(Oklch\\Colorspace::class);","handlingStrategy":"validation","validationCode":"// OKLAB -> OKLCH only stays in range when the derived chroma fits\n$a = $oklab->a()->value();\n$b = $oklab->b()->value();\n$chroma = sqrt($a * $a + $b * $b);\nif ($chroma > 0.4) {\n    $scale = 0.4 / $chroma;\n    $oklab = Oklab\\Color::create($oklab->lightness()->value(), $a * $scale, $b * $scale, $oklab->alpha()->normalized());\n}\n$oklch = $oklab->toColorspace(Oklch\\Colorspace::class);","typeGuard":"function isOklabWithinOklchChroma(OklabColor $color): bool\n{\n    $a = $color->a()->value();\n    $b = $color->b()->value();\n    return sqrt($a * $a + $b * $b) <= 0.4;\n}","tryCatchPattern":"try {\n    $oklch = $oklab->toColorspace(Oklch\\Colorspace::class);\n} catch (ColorException $e) {\n    // out-of-gamut corner: clamp a/b so chroma <= 0.4 and retry\n}","preventionTips":["Remember chroma max is 0.4 while a/b each allow 0.4, so diagonal colors overflow","Clamp a/b before converting saturated OKLAB colors","When interpolating in OKLab, keep results near the sRGB gamut before converting to OKLCH"],"tags":["color","oklab","oklch","colorspace","gamut","conversion","php"],"backgroundTag":"colorspace-conversion-failed","analyzedSha":"5598b9e39751c34afc5cdee84abef77f92c26f68","analyzedAt":"2026-08-23T02:17:31.068Z","schemaVersion":2},"datasetVersion":"2026-08-23T08:06:27.607Z"}