SSEOP : Skin-tone & Style Evaluation - Optimal Palette

이 모델은 사용자의 셀카 이미지를 기반으로 퍼스널 컬러 (계절톤) 분류와 의류 색상 분석을 수행하는 파이프라인을 제공합니다. OpenCV와 Mediapipe를 활용해 얼굴과 피부 영역을 추출하고, 참조용 종이(화이트 밸런스) 이미지를 이용해 피부색을 보정한 뒤, 계절별 컬러 팔레트와 비교하여 퍼스널 톤을 분류합니다. 또한 GrabCut을 통해 의류 마스크를 추출하고, K-Means 기반 색상 클러스터링으로 의류의 대표 색상과 비율을 시각화합니다. FastAPI를 이용한 간단한 웹 API도 함께 포함되어 있습니다.

---

목차

1. 프로젝트 구조
2. 설치 및 요구 사항
3. 사용 방법
   • 커맨드라인 실행 (main.py)
   • FastAPI 웹 서비스 (app.py)
4. 모듈 설명
   • main.py
   • analysis.py
   • clothes_personal_color.py
   • list.py
   • utils.py
   • app.py
5. 의존성
6. 참고

---

프로젝트 구조

/
├── main.py
├── analysis.py
├── clothes_personal_color.py
├── list.py
├── utils.py
├── app.py
├── requirements.txt         # (예시) 필요한 패키지 목록
└── input/
    ├── reference_paper.jpg  # 참조용 종이 이미지 (화이트 밸런스)
    └── selfie.jpg           # 분석할 셀카 이미지

• main.py
  • 전체 파이프라인을 순차적으로 실행하는 스크립트
• analysis.py
  • 피부색 보정, 퍼스널 컬러 분류, 의류 색상 분석 등 핵심 “분석” 로직이 구현된 모듈
• clothes_personal_color.py
  • 계절별 컬러 팔레트와 비교하여 퍼스널 톤을 분류하는 함수들이 정의된 모듈
• list.py
  • 봄·여름·가을·겨울별 CMYK 컬러 리스트를 정의하고, 이를 RGB 값으로 변환하여 저장
• utils.py
  • Mediapipe를 활용한 얼굴·피부 마스크 추출, 종이(참조) 컨투어 검출, GrabCut 기반 의류 마스크 추출 등 유틸리티 함수들
• app.py
  • FastAPI를 이용한 간단한 웹 서비스 예제. 이미지 업로드를 받아 퍼스널 톤과 의류 톤 정보를 반환

---

설치 및 요구 사항

1. GitHub에서 저장소를 클론합니다.

   git clone https://github.com/<사용자_이름>/<저장소_이름>.git
   cd <저장소_이름>

2. Python 3.7 이상(권장: 3.8+)이 설치되어 있어야 합니다.

3. requirements.txt 파일을 참고하여 필요한 패키지를 설치합니다.

   pip install -r requirements.txt

   주요 의존성 예시

   • opencv-python (OpenCV)
   • numpy
   • matplotlib
   • scikit-learn (KMeans)
   • mediapipe
   • fastapi
   • uvicorn

   _requirements.txt_ (예시)

   opencv-python
   numpy
   matplotlib
   scikit-learn
   mediapipe
   fastapi
   uvicorn
   

---

사용 방법

커맨드라인 실행 (main.py)

1. 사용자 셀카 이미지와 참조용 종이 이미지를 input/ 폴더에 준비합니다.

   • 예시:

     input/
     ├── reference_paper.jpg   # 조명 보정에 사용할 종이 이미지
     └── selfie.jpg            # 촬영한 셀카 이미지
     

2. 터미널에서 main.py를 실행합니다.

   python main.py

3. 프로그램이 순차적으로 다음 단계들을 수행합니다.

   1. 1단계: 얼굴·피부 마스크 추출
      utils.get_face_skin_mask() 함수를 통해 Mediapipe Face Mesh로부터 얼굴 윤곽을 찾고 피부 영역만 마스킹
   2. 2단계: 퍼스널 컬러 보정
      • utils.find_paper_contour_and_mask_refined()로 참조용 종이 컨투어를 검출하여 조명 보정용 마스크 생성
      • analysis.estimate_true_skin_color()를 통해 종이와 피부 마스크를 기반으로 피부의 “진짜” 색(조명 보정) 추정
   3. 3단계: 퍼스널 컬러(계절톤) 분류
      • analysis.classify_personal_color()를 이용해 HSL/HV 기준으로 봄·여름·가을·겨울 톤 중 하나를 선택
   4. 4단계: 의류 마스크 추출
      • utils.extract_clothes_mask() (GrabCut)으로 셀카에서 의류 영역 분리
   5. 5단계: 의류 색상 분석
      • analysis.get_dominant_colors_with_elbow_and_ratio()로 의류 마스크 영역에서 KMeans 클러스터링 수행
      • analysis.display_clothes_analysis_with_ratio()로 의류 내 주요 색상(클러스터)과 비율을 시각화 및 저장
   6. 최종 결과 이미지 및 단계별 중간 결과물을 지정된 경로에 저장하고, 콘솔에 메시지 출력

4. 완료 후, 저장된 이미지(조명 보정 전·후, 피부 마스크, 의류 마스크, 의류 색상 분석 결과 등)를 확인할 수 있습니다.

   • 예: results/skin_corrected.jpeg, results/clothes_mask.png, results/clothes_colors.png 등

---

FastAPI 웹 서비스 (app.py)

1. app.py를 실행하기 위해서는 uvicorn을 설치해야 합니다. (예: pip install uvicorn)

2. 아래 명령어로 FastAPI 서버를 구동합니다.

   uvicorn app:app --reload --host 0.0.0.0 --port 8000

3. 기본 제공되는 API 엔드포인트

   • 퍼스널 컬러 분석

     POST /personal-color
     

     • 요청 (multipart/form-data)
       • selfie: 사용자 셀카 이미지 (JPEG/PNG)
       • reference: 조명 보정용 종이 이미지 (JPEG/PNG)
     • 응답

       {
         "tone": "Spring",              # 예시: Spring / Summer / Autumn / Winter
         "hsv": { "h": 25.0, "s": 30.5, "v": 60.2 },   # 피부의 대표 HSV 값
         "corrected_skin_rgb": [200, 180, 170]        # 조명 보정 후 피부 색상 (RGB)
       }

   • 의류 톤 분석 (비율 포함)

     POST /clothes-color
     

     • 요청 (multipart/form-data)
       • selfie: 사용자 셀카 이미지
     • 응답

       {
         "dominant_colors": [
            { "rgb": [255, 0, 0], "ratio": 0.45 },
            { "rgb": [0, 128, 255], "ratio": 0.30 },
            { "rgb": [50, 50, 50], "ratio": 0.25 }
         ]
       }

   • 의류 톤 분류 (계절톤 비교)

     POST /clothes-tone
     

     • 요청
       • selfie: 사용자 셀카 이미지
     • 응답

       {
         "tone": "Autumn"   # 의류의 대표 색상을 기반으로 계절톤 분류
       }

4. 서버가 실행된 후 http://localhost:8000/docs로 접속하면 자동 생성된 Swagger UI에서 테스트 가능합니다.

---

모듈 설명

main.py

• 프로젝트의 엔트리 포인트 (Entry Point) 역할을 합니다.
• main() 함수 내에서 전체 파이프라인을 순차적으로 호출합니다.
  1. 입력 설정:

     base_dir = "."  
     INPUT_SELFIE_PATH = os.path.join(base_dir, "input/selfie.jpg")  
     INPUT_REFERENCE_PATH = os.path.join(base_dir, "input/reference_paper.jpg")  

  2. Step 1: 얼굴·피부 마스크 생성

     skin_mask = get_face_skin_mask(selfie_img_bgr)

  3. Step 2: 퍼스널 컬러 보정

     (
       true_skin_hsv,
       skin_lab_mean,
       corrected_selfie_bgr,
       exc_paper_mask_for_skin,
       refined_paper_mask
     ) = estimate_true_skin_color(selfie_img_bgr, skin_mask, INPUT_REFERENCE_PATH)

  4. Step 3: 퍼스널 톤 분류

     personal_tone = classify_personal_color(true_skin_hsv)

  5. Step 4: 의류 마스크 추출

     clothes_mask = extract_clothes_mask(corrected_selfie_bgr)

  6. Step 5: 의류 색상 분석

     dominant_colors, wcss_values = get_dominant_colors_with_elbow_and_ratio(
         corrected_selfie_bgr, clothes_mask
     )
     display_clothes_analysis_with_ratio(
         corrected_selfie_bgr, clothes_mask, dominant_colors, wcss_values
     )

  7. 각 단계별 중간 및 최종 결과 이미지를 results/ 폴더에 저장
  8. 콘솔 출력으로 진행 상황 및 결과 정보 표시

analysis.py

• 피부색 보정 & 추정
  • estimate_true_skin_color(selfie_img_bgr, extracted_face_skin_mask, reference_img_path)
    • selfie_img_bgr: 원본 BGR 셀카 이미지
    • extracted_face_skin_mask: Mediapipe로 추출한 피부 영역 바이너리 마스크
    • reference_img_path: 조명 보정용 종이 이미지 경로
    • 리턴:
      • true_skin_hsv: 조명 보정된 피부의 HSV
      • skin_lab_mean: Lab 색상 공간에서의 피부 평균값
      • corrected_selfie_bgr: 조명 보정된 셀카 BGR 이미지
      • exc_paper_mask_for_skin: 종이 영역을 제외한 피부 마스크
      • refined_paper_mask: 종이 영역 마스크(정제 버전)
    • 주요 흐름:
      1. 참조용 종이 컨투어 검출 (find_paper_contour_and_mask_refined)
      2. 종이 영역으로부터 그레이 스케일 보정 계수 계산
      3. 셀카 전체에 보정 계수 적용 → corrected_selfie_bgr
      4. 종이 영역 제외 후 피부 영역 H 값을 평균적으로 구해서 대표 피부색 산출
• 퍼스널 컬러 분류
  • classify_personal_color(true_skin_hsv)
    • Hue, Lightness, Saturation 등의 색상 지표를 기반으로 사전 정의된 계절별 기준 값과 비교해 Spring, Summer, Autumn, Winter 중 하나를 선택
• 의류 색상 분석
  • get_dominant_colors_from_mask(image_bgr, mask, k)
    • 마스크 영역 내 픽셀 색상값을 추출하여 KMeans 클러스터링을 수행하고, 각 클러스터의 중심(대표 색상)과 픽셀 수를 반환
  • get_dominant_colors_with_elbow_and_ratio(image_bgr, mask)
    • k 값을 Elbow 기법으로 자동 선정 후 클러스터링
    • 클러스터별 대표 색상(HSV 또는 RGB)과 비율 계산
  • display_clothes_analysis_with_ratio(image_bgr, mask, dominant_colors, wcss_values)
    • Matplotlib을 이용해
      1. 원본 이미지 위에 의류 영역 윤곽 표시
      2. 대표 색상 칩과 비율 그래프(파이 차트)
      3. Elbow 기법 결과 그래프
    • 결과물을 results/ 폴더에 PNG로 저장

clothes_personal_color.py

• CMYK ↔ RGB 변환
  • cmyk_to_rgb(c, m, y, k)
    • c, m, y, k 값을 0–100 스케일에서 0–1로 정규화 후, RGB로 변환
• 계절별 컬러 리스트에서 대표 색상 특징 추출
  • extract_tone_features(color_list)
    • list.py에 정의된 계절별 CMYK 리스트(spring_list, summer_list 등)를 입력받아
    • 각 색상의 HSL/HV 특징을 계산하여 tone_features 딕셔너리로 저장
• 퍼스널 톤 분류 함수
  • classify_tone_by_hsv(skin_hsv, tone_features)
    • 추정한 피부의 HSV 값을 받아 가장 가까운 계절 팔레트(톤) 이름(Spring, Summer, Autumn, Winter)을 반환
• 파일 로드 시, 미리 tone_features를 계산하여 메모리에 저장

list.py

• 계절별 CMYK 컬러 정보
  • spring_list, summer_list, autumn_list, winter_list에 여러 색상 항목(딕셔너리) 정의
    • 예시:

      spring_list = [
          { "name": "Peach", "c": 0, "m": 52, "y": 32, "k": 0, "season": "spring" },
          ...
      ]

  • 각 항목에는 name, c, m, y, k, season 키가 있으며, 코드 실행 시에 cmyk_to_rgb()를 통해 RGB 값("rgb")을 추가로 계산
• ΔE(CIELAB) 계산 (예: 색상 간 유사도 측정) 예비 함수
  • delta_e_distance(rgb1, rgb2) 등

utils.py

• Face Mesh를 이용한 얼굴·피부 마스크
  • get_face_skin_mask(image_bgr)
    • Mediapipe Face Mesh로 얼굴 윤곽점(landmarks)을 찾아서
    • FACE_OVAL_INDICES에 정의된 얼굴 테두리 점들을 연결해 다각형 마스크 생성
    • 다각형 내부를 채워 피부 영역 마스크(바이너리) 반환
• 참조용 종이(화이트 밸런스) 검출
  • find_paper_contour_and_mask_refined(image_bgr)
    • 그레이스케일, 가우시안 블러, 윤곽선 검출 등을 통해 종이(흰색 사각형) 컨투어 추출
    • 면적/기울기 조건을 통해 사각형 필터링
    • 정제된 종이 마스크(바이너리) 반환
• 의류 마스크 추출 (GrabCut 기반)
  • extract_clothes_mask(image_bgr)
    • 이미지 중앙을 기준으로 의류가 있다고 가정되는 사각형 영역(rect)을 설정
    • cv2.grabCut()을 사용하여 전경(의류) 영역만 분리
    • 이진화 마스크(0 또는 255)로 반환

app.py

• FastAPI 엔드포인트 정의

  • POST /personal-color:
    • Form-data로 업로드된 selfie, reference 이미지 파일을 받아
    • estimate_true_skin_color() → classify_personal_color() 순으로 호출
    • JSON 형식으로 퍼스널 톤(계절) 및 대표 HSV, RGB 정보 응답
  • POST /clothes-color:
    • Form-data로 selfie 이미지를 받아
    • get_face_skin_mask() → estimate_true_skin_color()(생략 가능) → extract_clothes_mask() → 색상 클러스터링
    • JSON으로 의류 대표 색상(rgb)과 비율(ratio)을 반환
  • POST /clothes-tone:
    • Form-data로 selfie 이미지를 받아
    • extract_clothes_mask() → get_dominant_colors_from_mask() → classify_tone_by_hsv()
    • 의류 톤(계절) 이름 반환

• CORS 설정

  • FastAPI 인스턴스 생성 시 CORSMiddleware를 추가하여 모든 출처 허용 설정

---

의존성

opencv-python>=4.5
numpy>=1.19
matplotlib>=3.3
scikit-learn>=0.24
mediapipe>=0.8
fastapi>=0.65
uvicorn>=0.13

---

참고

• 폴더 구조 예시

  ├── input/
  │   ├── selfie.jpg
  │   └── reference_paper.jpg
  ├── results/
  │   ├── corrected_selfie.jpg
  │   ├── paper_mask.png
  │   ├── skin_mask.png
  │   ├── clothes_mask.png
  │   └── clothes_analysis.png
  ├── main.py
  ├── analysis.py
  ├── clothes_personal_color.py
  ├── list.py
  ├── utils.py
  ├── app.py
  └── requirements.txt
  

• 결과물 예시

  1. skin_mask.png: 추출된 피부 영역 마스크 (흰색 = 피부)
  2. corrected_selfie.jpg: 화이트 밸런스 보정이 적용된 셀카
  3. clothes_mask.png: GrabCut으로 추출된 의류 영역 마스크
  4. clothes_analysis.png: 의류 대표 색상 및 비율 시각화 (파이 차트 + 색상 칩)