CIFStudio GUI + 헤드리스 검증 방법론
개요
크라우니 시뮬레이터(crownyc_win) 위에서 동작하는 CIFStudio GUI를 개발하면서, GUI 창 스크린샷에 의존하지 않는 4상균형3진 검증 체계를 확립했다.
문제
GUI 앱 개발 시 스크린샷 기반 검증의 한계:
- 창이 다른 창 뒤에 숨음 → osascript로 앞으로 가져오기 시도 → 터미널 창이 닫힘
- 매 변경마다 프로세스 kill → 재시작 → 스크린샷 → 확인 → 수정 사이클
- macOS 접근성 API 제한 (crownyc_win 커스텀 윈도우는 window 1 접근 불가)
해결: 4상균형3진 검증 구조
T(+1) = 성공 → 데이터 정합 확인
O( 0) = 실행 → 명령 수행 (컴파일+실행)
A(-1) = 실패 → 오류 검출
U = 구분 → 단계 분리
핵심 원칙
GUI 로직과 렌더링을 분리한다. GUI 코드에서 로직(색상변환, 필터, 씨앗 생성 등)을 독립 함수로 추출하고, 헤드리스 검증 도구가 이 함수들을 GUI 없이 호출하여 결과를 확인한다.
검증 11단계
| 단계 | 내용 | 검증 방법 |
|---|---|---|
| 1. 색상변환 | RGB→CIF3 색상인덱스 변환 | 순수색 R/G/B 분해 확인 |
| 2. 씨앗생성 | CIF그래픽 함수 출력 | 점/사각형/원 씨앗수+좌표+색상 |
| 3. 런렝스 | 맵 형식 런렝스 씨앗 | 너비/좌표 키 확인 |
| 4. 필터 | 흑백/반전/세피아/밝기 | 입출력 색상값 비교 |
| 5. 배열조합 | 다중 씨앗 배열 합치기 | 길이+요소 색상 확인 |
| 6. 데모이미지 | 전체 데모 생성 | 씨앗수 < VM 한도(1022) |
| 7. 줌맞춤 | 이미지→화면 비율 계산 | 27x27/100x100 피팅 값 검증 |
| 8. 원본백업 | 필터 전 백업, 수정 후 복원 | 깊은복사 독립성 확인 |
| 9. 좌표변환 | 화면→이미지 좌표 역산 | 줌16 기준 (5,3) 정합 확인 |
| 10. 픽셀검출 | 좌표→씨앗 색상 조회 | 상위 레이어 우선, 런렝스 범위 |
| 11. CIF3파일 | 저장 → 로드 왕복 | 씨앗 수 보존 확인 |
실행 방법
bashcd /Users/ef/CrownyOS/crownyc
# 1. 헤드리스 검증 (GUI 불필요 — 즉시 결과)
./hanseonc_high apps/CIFStudio_검증.한선 > /tmp/cif_verify.toau 2>/dev/null
./crownyc run /tmp/cif_verify.toau
# 2. 결과 예시
# T(통과): 30
# A(실패): 0
# 결과: 전체통과
# 3. GUI 확인 (필요시만)
./hanseonc_high apps/CIFStudio_GUI.한선 > /tmp/cifstudio_gui.toau 2>/dev/null
./crownyc_win --window run /tmp/cifstudio_gui.toau
관련 파일
| 파일 | 역할 |
|---|---|
apps/CIFStudio_GUI.한선 | GUI 메인 (867줄, 620KB TOAU) |
apps/CIFStudio_검증.한선 | 헤드리스 검증 (38개 테스트, 11단계) |
apps/CIFStudio.m | 네이티브 macOS 앱 (Cocoa) |
libs/CIF3.한선 | CIF3 포맷 라이브러리 |
libs/CIF그래픽.한선 | 그래픽 프리미티브 |
발견된 핵심 버그와 해결
- 색상 키 불일치: CIF3 씨앗은
"색상"키(색상인덱스 0~19682)를 사용하지만, 초기 렌더링 코드는"r","g","b"키를 읽음 → 전부 검정 렌더링. 색상분해 함수(색R27/색G27/색B27) 추가로 해결.
- VM 배열 한도 1022: 27×27 배경(729) + 원(~314) = 1043 > 1022 → 배열 오버플로. 런렝스 배경(27줄 = 27씨앗)으로 해결. 데모 전체 418씨앗.
- CIF필터 라이브러리 타입 불일치: CIF필터_* 함수는 36트릿 배열을 기대하지만, CIF그래픽 출력은 맵 형식 → 필터를 맵 형식 직접 처리로 재구현.
- 좌표 시스템: CIF그래픽(0기반 0~26) vs CIF3파일(균형3진 -13~+13). 데모를 중심기준 좌표(-13~+13)로 생성하여 자연 중앙정렬.
v2 개선 사항 (2026-05-22)
| 기능 | 설명 | 키/버튼 |
|---|---|---|
| 화살표 이동 | 캔버스 이동 (줌 비례) | 화살표 키 |
| 원본 복원 | 필터 적용 전 상태로 되돌리기 | R키, [원본] 버튼 |
| 줌 맞춤 | 이미지를 캔버스에 딱 맞게 | F키, [맞춤] 버튼 |
| 픽셀 색상 검출 | 캔버스 클릭시 해당 픽셀 색상 표시 | 캔버스 영역 클릭 |
| 마우스 좌표 표시 | 상태바에 이미지 좌표 실시간 | 자동 |
| 단축키 패널 | 사이드패널에 전체 키 목록 | 자동 표시 |
전 세션 적용 규칙
GUI 개발 시 반드시 헤드리스 검증 도구를 동반한다.
- 새 GUI 기능 추가 → 해당 로직의 헤드리스 테스트 추가
- 버그 수정 → 재현 테스트를 헤드리스 도구에 추가
- 스크린샷은 최종 확인용만 (개발 중 반복 사용 금지)
- 4상균형3진 출력: T=통과, A=실패, 숫자 집계