Color : conversion and analysis library

Java 21+ Record 기반으로 작성된 현대적이고 불변성(Immutable)을 보장하는 색상 도메인 라이브러리입니다.

전통적인 sRGB, HSL, CMYK 공간부터 최신 CSS Color Module Level 4 표준인 OKLab, OKLCH 및 CIE L*a*b*, L*u*v* 공간을 완벽히 지원하며, 색상 변환, CIEDE2000 색차 연산, WCAG 명암 대비율 검사, 색상 조화(Color Harmony) 팔레트 생성 기능을 제공합니다.

---

주요 특징 (Key Features)

• 불변성 및 스레드 안전성 (Immutable & Thread-safe): 모든 색상 모델이 Java record로 구현되어 복사/수정 시 안전합니다.
• 풍부한 색상 공간 지원: 총 9가지 주요 색상 모델 지원 (RGB, HSL, HSV, CMYK, XYZ, Lab, Luv, OKLab, OKLCH).
• 차세대 인지 균일 공간 (Perceptually Uniform Color Spaces): 지각적 왜곡이 없는 OKLab 및 OKLCH 연산 지원.
• 색상 조화 팔레트 추출 (Color Harmony): HSL/OKLCH 공간 기준 보색, 유사색, 3분할, 분할보색, 사각보색 팔레트 자동 생성.
• 색채학 연산 (Color Science):
  • Bradford 알고리즘 기반 전색순응(Chromatic Adaptation) 지원 (D65, D50 백색점 대응)
  • CIEDE2000 (\Delta E_{00}) 지각적 색차 연산
  • WCAG 2.1 웹 접근성 명암 대비율 (Contrast Ratio) 및 AA/AAA 적합성 검사

---

지원하는 컬러 모델 (Supported Color Models)

모든 컬러 모델은 ColorModel 최상위 Sealed Interface를 구현합니다.

모델	클래스	채널 범위	주요 특징 및 활용
sRGB	RgbColor	r, g, b (0.0 \sim 1.0)	표준 모니터 디스플레이 색상 표현, HEX 파싱 지원
HSL	HslColor	h (0^\circ \sim 360^\circ), s, l (0.0 \sim 1.0)	직관적인 색상, 채도, 명도 조작
HSV	HsvColor	h (0^\circ \sim 360^\circ), s, v (0.0 \sim 1.0)	그래픽 툴 및 디지털 아트 컬러 픽커
CMYK	CmykColor	c, m, y, k (0.0 \sim 1.0)	인쇄 및 감산혼합(Subtractive) 색상 표현
CIE XYZ	XyzColor	x, y, z (기본 D65 기준)	색채학의 기본이 되는 삼자극치 Absolute 공간
CIE Lab*	LabColor	l (0 \sim 100), a, b (약 -128 \sim +127)	CIE 1976 인지 균일 공간 및 전통적 색차 연산
CIE Luv*	LuvColor	l (0 \sim 100), u, v (약 -100 \sim +100)	발광체(Display) 및 가법혼합용 인지 균일 공간
OKLab	OklabColor	l (0.0 \sim 1.0), a, b (약 -0.4 \sim +0.4)	보라색 픽셀 왜곡을 보정한 차세대 지각 균일 공간
OKLCH	OklchColor	l (0.0 \sim 1.0), c (\ge 0), h (0^\circ \sim 360^\circ)	OKLab의 원통형 좌표계 (CSS4 표준, 자연스러운 그래디언트)

모든 모델은 투명도 채널인 alpha (0.0 \sim 1.0)를 기본으로 포함합니다.

---

설치 방법 (Installation)

Gradle (Kotlin DSL)

repositories {
  maven {
    name = "Elex Repository"
    url = uri("https://artifacts.elex-project.com/repository/maven/")
  }
}
dependencies {
    implementation("com.elex_project:elex-color:1.0.0")
}

---

사용 예시 (Usage Examples)

1. 색상 객체 생성 (Color Creation)

// 1. HEX 코드 파싱
RgbColor brandColor = RgbColor.fromHex("#3498DB");

// 2. 0~255 정수 값으로 RGB 생성
RgbColor red = RgbColor.fromRgb255(255, 0, 0);

// 3. OKLCH 색상 생성 (Lightness, Chroma, Hue)
OklchColor oklch = new OklchColor(0.65, 0.2, 250.0);

// 4. CMYK 색상 생성 (Cyan, Magenta, Yellow, Key)
CmykColor printColor = new CmykColor(0.0, 0.8, 0.6, 0.1);

---

2. 색상 공간 변환 (Color Conversions)

모든 색상 모델 객체는 Fluent API를 제공하여 직관적으로 타 색상 공간으로 변환할 수 있습니다.

RgbColor rgb = RgbColor.fromHex("#8E44AD");

// RGB -> OKLCH 변환
OklchColor oklch = rgb.toXyz().toOklab().toOklch();

// OKLCH -> HEX 문자열
String hex = oklch.toHex(); // "#8E44AD"

// RGB -> CMYK 변환
CmykColor cmyk = rgb.toCmyk();

// RGB -> CIE L*a*b* 변환
LabColor lab = rgb.toLab();

---

3. 색상 조화 팔레트 추출 (Color Harmony)

단일 기준 색상으로부터 보색, 유사색, 3분할, 분할보색 팔레트를 생성합니다. (OKLCH 인지 균일 모드 및 HSL 모드 지원)

import com.elex_project.color.harmony.Harmony;
import com.elex_project.color.model.RgbColor;
import com.elex_project.color.ColorModel;
import java.util.List;

RgbColor baseColor = RgbColor.fromHex("#E74C3C");

// 1. 보색 팔레트 (2색) - OKLCH 공간 기준 (기본값)
List<ColorModel> complementary = Harmony.complementary(baseColor);

// 2. 유사색 팔레트 (3색 - 기준 색상 ±30도)
List<ColorModel> analogous = Harmony.analogous(baseColor, 30.0, Harmony.Mode.OKLCH);

// 3. 3분할 팔레트 (3색 - 120도 간격)
List<ColorModel> triadic = Harmony.triadic(baseColor);

// 4. 분할보색 팔레트 (3색 - 보색 ±30도)
List<ColorModel> splitComp = Harmony.splitComplementary(baseColor);

// 결과 HEX 출력
List<String> hexPalette = splitComp.stream()
        .map(color -> color.toRgb().toHex())
        .toList();

---

4. 접근성 및 색차 연산 (Accessibility & Color Metrics)

import com.elex_project.color.metric.ColorMetric;
import com.elex_project.color.model.LabColor;
import com.elex_project.color.model.RgbColor;

RgbColor text = RgbColor.fromRgb255(255, 255, 255); // 흰색
RgbColor bg = RgbColor.fromRgb255(30, 144, 255);    // 파란색

// 1. WCAG 2.1 명암 대비율 (Contrast Ratio) 연산
double contrast = ColorMetric.contrastRatio(text, bg); // 예: 4.54:1

// 2. WCAG AA / AAA 등급 적합성 검사
boolean passAA = ColorMetric.isWcagAa(text, bg, false);   // 일반 텍스트 기준 (>= 4.5)
boolean passAAA = ColorMetric.isWcagAaa(text, bg, false); // 일반 텍스트 기준 (>= 7.0)

// 3. CIEDE2000 지각적 색차 연산 (ΔE_00)
LabColor colorA = new LabColor(50.0, 2.5, 0.0);
LabColor colorB = new LabColor(52.0, 3.0, 1.0);

double deltaE = ColorMetric.deltaE2000(colorA, colorB);
// deltaE < 1.0 이면 사람이 눈으로 두 색의 차이를 구분하기 힘듦

---

5. 백색점 전색순응 (Chromatic Adaptation)

import com.elex_project.color.space.Illuminant;
import com.elex_project.color.model.XyzColor;

XyzColor d65White = Illuminant.D65.toXyz();

// Bradford Transform 알고리즘을 통한 D65 -> D50 백색점 변환
XyzColor d50White = Illuminant.adapt(d65White, Illuminant.D65, Illuminant.D50);

---

설계 및 아키텍처 (Design & Architecture)

• Sealed Type Hierarchy: ColorModel 인터페이스는 permits 키워드를 통해 허용된 Record 타입만 구현 가능하도록 제한하여 Pattern Matching 시 완벽한 컴파일 타임 검증을 제공합니다.

public sealed interface ColorModel 
    permits RgbColor, HslColor, HsvColor, CmykColor, XyzColor, LabColor, LuvColor, OklabColor, OklchColor { ... }

• Compact Constructors Validation: 모든 색상 모델은 생성 시 채널 범위를 즉시 검증하며, 잘못된 수치(예: NaN, 범위 초과값) 입력 시 IllegalArgumentException을 발생시킵니다.

---

라이선스 (License)

This project is licensed under the Apache License – see the LICENSE file for details.

---

Copyright © 2026 Elex Project. All rights reserved.

https://www.elex-project.com/