애니메이션 생성

[solidSnakesado]

[1] 애니메이션 생성 부분
성공 애니메이션 파이프라인 (행동 결정 → 물리 참고값 계산 → Keyframe 설계 → 수치 보정)
정답 클릭 시점에만 실행되며, 오브젝트별로 "어떤 움직임을", "어떤 물리 기반으로", "AI가 어떻게 설계할지"를 단계별로 결정한다.
AI는 애니메이션 설계를 담당하고 엔진은 실행만 담당한다. 이 분리로 안정성을 확보하고 CPU 환경에서도 배포 가능하게 한다.

💡 파이프라인 실행 조건
정답 클릭 시에만 파이프라인 전체가 실행된다.
오답 클릭과 호버에는 아무 반응 없음.
(호버/오답 반응은 위치 힌트가 되므로 의도적으로 배제)

📊 파이프라인 입력 — 오브젝트 정보
오브젝트 식별 정보
의미 분류: 카테고리 / 서브카테고리
공간·크기 정보: 위치 좌표, 장면 내 관계
시각 상태: 가림 비율
물리 속성: 재질 / 무게 / 크기 분류

📊 파이프라인 출력 — 애니메이션 설정 전체
프레임별 위치·회전·크기·투명도·발광 정보
재생 시간
보간 곡선
변환 기준점
반복 여부 / 완료 후 처리 / 파티클 효과 여부 : 파이프라인 고정값 (AI 개입 불가)

[2] 행동 결정 부분
가장 먼저 선행되어야 하는 것은 "이 오브젝트를 어떤 방식으로 움직일지"를 결정하는 것이고,
그 결과가 이후 물리 계산과 Keyframe 설계 전체의 방향을 결정한다.

*참고로 현재 오브젝트라고 정의한 것은 배경과는 별개로 분리된 Object Layer들이다.

결정 우선순위 (높은 것이 먼저 적용)

1. 억제 규칙 — 조건 해당 시 미세 burst로 강제 교체
2. 장면 내 관계 — 매달린 구조 → 진자 운동 등
3. 오브젝트 의미 — 동물 종류, 탈것 종류 등 서브카테고리 기반
4. 카테고리 기본 매핑 — 동물 → 점프, 원형 물체 → 회전 등
5. fallback — 위 규칙 중 매칭 없으면 기본 진동

📍 억제 규칙
숨은그림찾기의 핵심 보호 장치. 정답 클릭 이후에도 오브젝트가 크게 움직이면
인접한 미발견 오브젝트의 위치까지 노출될 수 있다.
→ 크기 변화만 허용하는 미세 burst로 대체해서 피드백은 주되 위치 노출은 방지.

억제 조건 (OR 조건 — 하나라도 해당하면 강제 교체)

1. 가림 비율이 높은 오브젝트
   → 크게 움직이면 인접 미발견 오브젝트 위치 노출 위험
2. 매우 작은 오브젝트
   → 이동·회전이 주변 대비 과도하게 눈에 띔

억제 조건이 존재하는 이유
가림 비율 기준: 절반 이상 가려지면 움직임 자체가 위치 신호가 됨
크기 기준: 작은 오브젝트에서 큰 이동은 크기 대비 과함

📍 타입별 움직임 분류

타입	발동 조건	움직임 특징
점프	동물 계열 오브젝트	위로 튀어오름. 준비 → 상승 → 착지
진자	매달린 구조의 오브젝트	좌우 회전 감쇠. 위쪽 기준점 고정
기본 진동	fallback (기본값)	제자리 회전 진동
Y축 회전	바퀴·동전 등 회전 물체	좌우 압축·복원으로 Y축 회전 표현
수평 이동	수평 방향 특성 물체	좌우 감쇠 진동
미세 burst	억제 규칙 해당 오브젝트	크기 변화만. 위치·회전 변화 없음

💡 설계 노트
향후 확장 방향:
현재 규칙 기반(Rule-based) 결정 구조를 유지하되,
내부 결정 로직만 AI 기반으로 교체 가능하도록 입출력 인터페이스를 고정함.
입력(오브젝트 정보) → 출력(움직임 타입 + 억제 여부)의 계약은 변경되지 않음.

[3] 물리 파라미터 계산 부분
채택한 물리 설계 요소
가장 먼저 선행되어야 하는 건 "물리적으로 타당한 움직임"을 위한 수치 기반을 만드는 것이고,
그 다음에 이어지는 AI의 Keyframe 설계가 이 수치를 참고값으로 활용한다.

*참고로 물리 참고값은 AI를 구속하지 않는다. AI가 최종 수치를 자유롭게 결정하되
현실적인 움직임의 기준선으로 활용하는 용도이다.

현재 오브젝트로부터 얻을 수 있는 물리 정보의 종류
📍 from. 오브젝트 속성
물리적인 요소) 재질 | 무게 | 크기 분류
공간적인 요소) 가림 비율 | 면적

📍 from. 행동 결정 결과
결정된 움직임 타입 | 억제 여부

📍 from. 물리 수식
감쇠계수: 재질 특성 × 무게 보정
진폭: 크기 기반 기본값 → 가림 비율이 높으면 억제
각주파수: 움직임 타입별 수식 적용
지속시간: 위 값에서 도출

1. 타입별 물리 파라미터 계산 방식

진자 운동
근거: 실제 진자 물리법칙 적용. 매달린 높이가 높을수록 느리게 흔들림.
설계 의도: 오브젝트의 장면 내 위치 관계를 수치에 반영.

점프
근거: 오브젝트 크기에 따라 튀어오르는 높이 차별화.
설계 의도: 작은 물체는 낮게, 큰 물체는 높게 튀어오르는 자연스러운 비례 관계.

미세 burst (억제 오브젝트 전용)
근거: 진폭 매우 작게, 감쇠 매우 빠르게.
설계 의도: 찾았다는 피드백은 주되 위치는 노출하지 않는 효과.

기본 진동 / Y축 회전 / 수평 이동
근거: 각 움직임 특성에 맞는 진동 수식 적용.

2. 물리 파라미터 계산 후 AI 전달 방식
   산출된 값은 AI에 "참고값으로만" 전달.
   AI가 최종 수치를 결정하며, 참고값을 초과하거나 무시할 수 있음.

📊 물리 파라미터 계산 요약

계산 항목	입력 데이터	계산 방식	용도
감쇠계수	재질, 무게	재질 특성값 × 무게 보정 계수	AI 참고값
진폭	크기 분류, 가림 비율	크기 기반 기본값 → 가림 억제	AI 참고값
각주파수	움직임 타입, 공간 정보	타입별 물리 수식	AI 참고값
지속시간	위 값에서 도출	진폭·감쇠 기반	AI 참고값
미세 burst	억제 여부	별도 고정 파라미터 세트	AI 참고값

💡 설계 노트
물리 계산을 AI 호출과 분리한 이유:
AI 없이도 물리 수식만으로 Keyframe을 직접 계산하는 fallback이 가능.
물리 파라미터 계산은 항상 실행되며 Keyframe 생성 단계의 입력을 준비하는 역할.

[4] Keyframe 생성 부분
채택한 Keyframe 설계 방식
가장 먼저 선행되어야 하는 건 "AI가 물리 참고값을 바탕으로 프레임별 좌표를 직접 설계"하는 것이고,
그 다음에 이어지는 파이프라인 고정값 주입과 수치 보정이 최종 애니메이션 설정을 완성한다.

*참고로 파이프라인이 고정하는 값은 AI가 개입할 수 없다. 게임 일관성과 UX 보호를 위한 설계 선택이다.

현재 AI에게 제공하는 컨텍스트 종류
📍 오브젝트 정보 컨텍스트
의미 분류: 카테고리, 서브카테고리
물리 속성: 재질, 무게, 크기
공간 상태: 가림 비율, 장면 내 관계

📍 물리 참고값 컨텍스트
감쇠계수 / 진폭 / 각주파수 / 지속시간 / 타입별 참고값

📍 AI 설계 제약 컨텍스트
이동 방향 제한: 위로만 이동 (아래로 내려가는 것 금지)
이동·회전·크기 변화 허용 범위 명시
억제 오브젝트: 크기 변화만 허용. 위치·회전 변화 없음.

1. AI 생성 경로 (AI 호출 가능할 때)
   오브젝트 컨텍스트 + 물리 참고값 → AI에 제공
   AI가 프레임별 위치·회전·크기·투명도·발광, 재생 시간, 보간 곡선, 변환 기준점 직접 설계
   응답 파싱 → 억제 오브젝트 보정(위치·회전 강제 제거) → 마지막 프레임 투명도 주입

AI 타입별 설계 가이드라인 (제약 조건으로 제공)
점프 : 준비 동작(압축) → 상승(늘어남) → 착지(압축). 수직 이동 사용. 발 기준점.
진자 : 최대 각도에서 시작, 좌우 회전 감쇠 패턴. 상단 기준점.
기본 진동: 중립에서 시작하는 회전 진동. 미세 크기 변화 추가.
Y축 회전: 좌우 압축·복원으로 Y축 회전 표현. 중심 기준점.
수평 이동: 좌우 감쇠 진동. 중심 기준점.
미세 burst: 크기 변화만. 위치·회전 없음.

2. 수식 fallback 경로 (AI 호출 불가 시)
   AI 없이 물리 수식으로 프레임별 좌표 직접 계산 → Keyframe 생성
   AI 의존도 없이 완전 동작 보장.

3. 공통 후처리 (경로 무관)
   프레임 데이터 구조 변환
   보간 곡선 / 변환 기준점 유효성 검사 및 보정

4. 파이프라인 고정값 주입 (AI 개입 불가)
   아래 값은 AI에게 제약 조건으로 사전 고지하고, 후처리에서도 강제 적용된다.

고정값 항목	설계 이유
발견 후 반투명	찾은 오브젝트임을 시각적으로 확인시킴
1회 재생	성공 애니메이션은 반복 없이 1회만
완료 후 dim 처리	완료 후 반드시 흐리게 처리
파티클 효과	가림 비율 기반으로 자동 결정
발광 반경	오브젝트 크기에 비례하여 자동 결정

📊 Keyframe 설계 매핑 요약

단계	처리 경로	핵심 산출물
AI 컨텍스트 구성	오브젝트 정보 + 물리 참고값	AI에 전달할 입력 구성
AI 설계	AI 호출 → 응답 파싱	프레임별 좌표, 보간 곡선, 기준점
억제 보정	미세 burst 강제 적용	위치·회전 변화 제거
파이프라인 값 주입	고정값 덮어쓰기	투명도, 반복 여부, 완료 처리, 파티클
fallback	물리 수식 직접 계산	AI 없이도 완전 동작

💡 설계 노트 (핵심 설계 변경 이력)
기존 구조: 물리 수식이 좌표 계산 → AI가 배율만 조정
변경 구조: 물리 수식은 참고값 제공 → AI가 좌표를 직접 설계
변경 이유: AI가 오브젝트 의미(재질·맥락·장면 관계)를 반영한 자연스러운 움직임 설계 가능.
물리 수식은 현실적인 기준선 역할에만 집중.

[5] 최종 파이프라인
🏗️ 성공 애니메이션 4단계 연쇄 파이프라인
본 파이프라인은 "행동 결정 → 물리 참고값 계산 → Keyframe 설계 → 수치 보정"을 순차 실행하며,
각 단계의 출력이 다음 단계의 입력이 되는 연쇄 구조로 설계되었습니다.

🔄 실행 시퀀스
[단계 1] 행동 결정 → 움직임 타입 + 억제 여부
[단계 2] 물리 계산 → 타입별 물리 참고값
[단계 3] Keyframe 설계 → 프레임별 좌표 전체
[단계 4] 수치 보정 → 최종 애니메이션 설정 (엔진 전달용)

📍 단계 1: 행동 결정
입력: 오브젝트 전체 정보
연쇄 프로세스:
억제 조건 판단 → 미세 burst 강제 여부 결정
장면 관계 → 오브젝트 의미 → 카테고리 순으로 움직임 타입 결정
매칭 없으면 기본 진동 (fallback)
출력: 움직임 타입 + 억제 여부 + 결정 근거

📍 단계 2: 물리 계산
입력: 오브젝트 정보 + 행동 결정 결과
연쇄 프로세스:
재질·무게 기반 감쇠계수 산출
크기·가림 비율 기반 진폭 산출
움직임 타입별 수식으로 각주파수·지속시간 계산
억제 오브젝트인 경우 별도 고정 파라미터 세트 반환
출력: 감쇠계수, 진폭, 각주파수, 지속시간, 타입별 참고값

📍 단계 3: Keyframe 설계
입력: 오브젝트 정보 + 행동 결정 결과 + 물리 참고값 + AI 연결 여부
연쇄 프로세스 (AI 경로):
오브젝트 컨텍스트 + 물리 참고값 구성 → AI 설계 → 응답 파싱
억제 오브젝트 보정(위치·회전 강제 제거) → 파이프라인 고정값 주입
연쇄 프로세스 (fallback 경로):
AI 연결 불가 또는 호출 실패 → 물리 수식으로 Keyframe 직접 생성
출력: 프레임별 좌표 전체 + 재생 시간 + 보간 곡선 + 기준점 + 파이프라인 고정값

📍 단계 4: 수치 보정
입력: Keyframe 설계 결과
연쇄 프로세스:
재생 시간 허용 범위 클램핑
이동·회전·크기 변화 허용 범위 클램핑
프레임 시간 오름차순 정렬
시작·종료 프레임 자동 보완
예외 발생 대신 클램핑으로 처리 (UX 우선)
출력: 최종 애니메이션 설정 (엔진 전달용)

📋 파이프라인 요약 테이블

단계	실행 순서	분기 발생 조건	핵심 산출물
행동 결정	1순위	억제 조건 해당 → 미세 burst 강제	움직임 타입, 억제 여부
물리 계산	2순위	억제 오브젝트 → 고정 파라미터 세트	감쇠계수, 진폭, 각주파수
Keyframe	3순위	AI 연결 가능 여부 → AI 설계 / 수식	프레임별 좌표 전체
수치 보정	4순위	없음 (항상 실행)	최종 애니메이션 설정

💡 설계 노트
설계 분리 원칙:
AI는 애니메이션 설정(config)을 생성하고, 엔진은 실행만 담당.
이 분리로 안정성 확보 및 AI 없이도 완전 동작 가능.

데이터 전달 원칙:
각 단계는 독립적으로 동작하며, 이전 단계의 출력만을 입력으로 받음.
단계 간 직접 참조 없음.

fallback 보장:
AI 연결 불가 또는 호출 실패 시 물리 수식 기반으로 자동 전환.
AI 의존도 없이 완전 동작 보장.

수치 보정 우선 원칙:
범위 초과 시 예외를 발생시키지 않고 클램핑.
하나의 오브젝트 애니메이션이 멈추는 것보다 보정값으로 실행되는 것이 UX 상 낫다.

[solidSnakesado]

애니메이션 진행 중 포지션 변경에 따른 모션 애니메이션을 생성하는 방향도 고려

[solidSnakesado]

[solidSnakesado]

WAN I2V 자동 모션 애니메이션 파이프라인 — 진행 현황 (1주차)

마지막 업데이트: 2026-03-06

---

프로젝트 개요

스프라이트 이미지(PNG)를 입력받아 자동으로 모션 애니메이션을 생성하는 파이프라인.

• 모션 생성 모델: Wan2.1-I2V-14B-480P (Alibaba 공식) — Q3_K_S GGUF 양자화 버전 (city96 변환)
• 실행 환경: ComfyUI
• 분석/검증 모델: Gemini 2.5 Flash
• 파이프라인 언어: Python

---

전체 흐름

이미지 입력 (PNG)
    ↓
1. Gemini Vision 분석 (wan_vision_analyzer.py)
   - 대상 파악
   - 가장 아이코닉한 동작 결정
   - fps, motion 기준값, positive/negative 프롬프트 생성
    ↓
2. 이미지 전처리 (wan_backend.py)
   - 480×480 캔버스, scale=0.65, headroom 적용
    ↓
3. WAN I2V 생성 (ComfyUI)
   - steps=35, cfg=7.0, timeout=1800s
   - 완료 감지: status.completed OR status_str 확인
    ↓
4. 수치 검증 (wan_validator.py)
   - no_motion, too_slow, too_fast
   - repeated_motion (max_peaks=4)
   - frame_escape (배경색 자동 감지 기반)
   - no_return_to_origin (max_diff=0.20)
   - center_drift (max=0.12) ← 위치 이동 감지
    ↓ 실패
5. AI 검증 (wan_ai_validator.py)
   - Gemini가 원본 + 첫/중간/마지막 프레임 비교
   - 파싱 실패 시 실패 처리 (통과 처리 금지)
   - 2회 재시도
    ↓ 실패 → AI 조정 (fps, scale, 프롬프트) → 재생성
    ↓ 통과
6. 배경 제거 후처리 (wan_bg_remover.py)
   - flood fill 기반 배경 제거
   - 배경색 자동 감지 (흰색/검정/보라 등 무관)
   - 투명 PNG 시퀀스 + APNG 저장
    ↓
저장 ✅

---

파일 구성

파일	역할
wan_vision_analyzer.py	Gemini Vision 분석 → 동작/수치/프롬프트 결정
wan_backend.py	전체 파이프라인 오케스트레이터
wan_validator.py	수치 기반 검증 (7개 항목)
wan_ai_validator.py	Gemini Vision AI 검증 + 조정
wan_bg_remover.py	배경 제거 후처리 (신규)

---

핵심 설계 원칙

1. AI 주도 설계

• 고정 프리셋/규칙 없음
• Gemini가 이미지를 보고 모든 것을 자유롭게 결정
• 카테고리 분류 없음 (Animals, Plants 등 예시 목록 제거)

2. IN-PLACE 모션 원칙

• 캐릭터 위치 이동 없이 제자리에서만 동작
• 점프 → 다리 압축/신장, 스쿼시-스트레치 (위치 고정)
• 날기 → 날개짓만, 앞으로 이동 없음
• center_drift 검증으로 위치 이동 감지

3. 가장 아이코닉한 동작 선택

• 미세 동작(throat pulse, 호흡, 눈 깜빡임) 금지
• WAN이 표현 가능한 크고 명확한 동작 선택
• e.g. 개구리 → 점프, 새 → 날개짓, 물고기 → 헤엄

4. Fallback 없음

• Gemini 실패 시 최대 3회 재시도
• 3회 모두 실패 시 RuntimeError (잘못된 결과 생성 방지)

---

검증 항목 (wan_validator.py)

항목	설명	기준값
no_motion	움직임 없음	motion < min*0.5
too_slow	너무 느림	motion < min_motion
too_fast	너무 빠름	motion > max_motion
repeated_motion	반복 동작	peaks > 4
frame_escape	화면 이탈	edge_ratio > 0.08
no_return_to_origin	원본 미복귀	return_diff > 0.20
center_drift	위치 이동	drift > 0.12

motion 기준: CHARACTER PIXEL 기준 (배경 제외) → 전체 픽셀 기준보다 5~10배 높음

---

AI 검증 항목 (wan_ai_validator.py)

항목	설명
speed_too_fast	속도 너무 빠름
speed_too_slow	속도 너무 느림
no_motion	동작 없음
no_return_to_origin	원본 포즈 미복귀
frame_escape	화면 이탈
unnatural_movement	부자연스러운 동작
character_inconsistency	캐릭터 불일치
background_color_change	배경색 변화

---

주요 모델 정보

메인 생성 모델:
  Wan2.1-I2V-14B-480P (Alibaba 공식)
  파일: wan2.1-i2v-14b-480p-Q3_K_S.gguf
  → Q3_K_S GGUF 양자화 버전 (city96 변환)

텍스트 인코더:
  UMT5-XXL FP8: umt5_xxl_fp8_e4m3fn_scaled.safetensors

이미지 인코더:
  CLIP Vision H: clip_vision_h.safetensors

VAE:
  wan_2.1_vae.safetensors

분석/검증:
  Gemini 2.5 Flash

---

테스트 결과

개구리 (frog_more_legroom.png) — 10회 × 2세트

1차 세트 (이전 버전)

• 주요 실패: repeated_motion, frame_escape, no_return_to_origin
• AI 조정이 작동하여 scale 0.65→0.55, 프롬프트 추가됨
• 10회 모두 실패

2차 세트 (수정 후)

• Gemini가 "throat pulse (목구멍 팽창)" 동작 선택
• 문제: WAN이 미세 동작 표현 불가 → no_motion, too_slow 반복
• AI validator 파싱 오류 ("expected string or bytes-like object") 반복
  → 통과 처리로 조정 없이 10회 반복
• 배경이 보라색/검정으로 변하는 현상 발생
• 10회 모두 실패

확인된 문제점 및 수정 내용:

문제	원인	수정
throat pulse 반복 선택	시스템 프롬프트 미세 동작 허용	아이코닉 동작 강제, 미세 동작 금지
AI validator 파싱 오류 → 통과 처리	except에서 passed=True 반환	실패 처리 + 2회 재시도
edge_ratio 오탐 (배경 변색)	흰색 고정 기준	첫 프레임 테두리색 자동 감지
fps 조정 누락	AI 조정 지시 부족	no_motion/too_slow 시 fps 증가 지시 추가
배경색 변화 미감지	검증 항목 없음	background_color_change 항목 추가
배경 변색 후처리 없음	후처리 미구현	wan_bg_remover.py 신규 구현

---

현재 상태

• 파이프라인 기본 구조
• Gemini Vision 분석 (wan_vision_analyzer.py)
• WAN I2V 생성 + ComfyUI 연동
• 수치 검증 7개 항목
• AI 검증 + 조정
• center_drift 위치 이동 감지
• 배경 제거 후처리 (wan_bg_remover.py)
• AI validator 파싱 오류 수정
• edge_ratio 배경 변색 오탐 수정
• 새 이미지 (bird_with_room.png) 테스트 진행 중

---

다음 단계

1. bird_with_room.png 테스트

   • 날개짓 동작 생성 확인
   • 수정된 시스템 프롬프트 효과 검증

2. 키프레임 경로 구현 (추후)

   • 색상 변화, 단순 변형 등 WAN 불필요한 경우
   • animation_analyzer.py로 경로 판단

3. 다양한 이미지 테스트

   • 물고기, 식물, 오브젝트 등

---

실행 방법

cd ~/anim_pipeline
source animVenv/bin/activate

python3 -c "
import os, logging
logging.basicConfig(level=logging.INFO)
from dotenv import load_dotenv
load_dotenv()
from image_pipeline.sprite_gen.wan_backend import WanBackend

backend = WanBackend(
    api_key=os.environ['GEMINI_API_KEY'],
    comfyui_url='http://127.0.0.1:8188',
    output_dir='outputs/wan',
)
result = backend.generate('/home/sado/ComfyUI/input/bird_with_room.png')
print(result)
"

---

배포 파일 위치

~/anim_pipeline/image_pipeline/sprite_gen/
├── wan_vision_analyzer.py   ← 분석
├── wan_backend.py           ← 오케스트레이터
├── wan_validator.py         ← 수치 검증
├── wan_ai_validator.py      ← AI 검증
└── wan_bg_remover.py        ← 배경 제거 (신규)

[solidSnakesado]

1주차 개발 개요

생성 기준: 2026-03-06 ~ 2026-03-08
목적: 검증 개발 과정 + 프롬프트 개선 과정 + 기능 수정 기록

---

목차

1. [1주차 개발 개요]
2. [파이프라인 전체 구조 (1주차)]
3. [개발 히스토리 (시간순)]
   • 3-1. [기반 구축 — ComfyUI 연동 + 워크플로우]
   • 3-2. [최초 테스트 — 물고기 + 화질 문제]
   • 3-3. [Validator 구현 + 버그 수정]
   • 3-4. [프롬프트 전략 전환 — 영어→중국어]
   • 3-5. [개구리 테스트 — 점프 사이클 문제]
   • 3-6. [pingpong 도입 + AI Validator 비디오 직접 피드]
   • 3-7. [물고기 APNG 완성 + frame_escape 오판정 수정]
   • 3-8. [새(bird) 테스트 — BG 문제 + 날개 flap 10회 실패]
   • 3-9. [마스킹 파이프라인 도입 + 후처리 합성 전환]
   • 3-10. [합성 순서 버그 + 액션 전환 로직 추가]
   • 3-11. [수치 검증 대규모 오탐 수정]
   • 3-12. [Ghosting 감지 강화 + 프롬프트 누적 제거]
   • 3-13. [암전 방지 + SOFT_ISSUES 수정 + 테스트 캐릭터 생성]
   • 3-14. [successful_results 루프 수정 + 이미지 분리]
4. [검증 시스템 발전 과정]
5. [프롬프트 개선 과정]
6. [핵심 설계 결정 배경 (Why)]
7. [최종 파일 현황 + 설정값]
8. [PENDING]

[solidSnakesado]

---

1. 개발 개요

두 파이프라인 공존

기존 파이프라인 (pipeline.py, layer1_decision.py, layer2a_physics.py, layer2b_ai_keyframe.py):

• 스프라이트 PNG → 규칙/물리 기반 + AI Keyframe → CSS/Web Animation
• LLM이 Keyframe 좌표를 직접 설계, CPU 배포 가능

WAN I2V 파이프라인:

• 스프라이트 PNG → Gemini Vision 분석 → ComfyUI WAN 모델 → 수치+AI 이중 검증 → 배경 제거 → APNG
• GPU 필수, Wan2.1-i2v-14b 모델 사용

핵심 설계 원칙 (완성본 기준)

1. AI 주도 — 고정 규칙 없이 Gemini가 동작/수치/프롬프트 전부 결정
2. IN-PLACE 모션 — 위치 이동 없이 제자리 동작만 (center_drift 검증으로 감지)
3. 아이코닉한 동작 — 미세 동작(호흡, 눈 깜빡임) 금지, WAN이 표현 가능한 큰 동작만
4. 분류 코드 없음 — 동물/탈것 분류 기반 분기 전체 제거 (Gemini가 자유 판단)

---

[solidSnakesado]

2. 파이프라인 전체 구조

현재 설정값

항목	값	비고
해상도	480×480
steps	20	원래 30 → 33% 시간 단축
pingpong	True	순방향→역방향 루프로 이음새 완화
frames	AI 동적 결정	1781 범위, 권장 1749
MAX_RETRIES	5	⚠️ 테스트용 — 운영 시 10으로 복구 필요
WAN 모델	wan2.1-i2v-14b-480p-Q3_K_S.gguf
Gemini 모델	gemini-2.5-flash	분석 + 검증 모두 사용

실행 흐름 (wan_backend.py)

generate(image_path)
  │
  ├─ Step 0: preprocess_image_simple()
  │    이미지를 480×480 흰색 캔버스에 배치 (scale=0.65, headroom_top=0.18)
  │    _white_anchor(): 배경 순백색 강제 + 경계 선명화
  │    검정 배경 이미지도 자동 흰 배경으로 변환됨
  │
  ├─ Step 1: WanVisionAnalyzer.analyze()
  │    Gemini Vision으로 이미지 분석 → 액션·프롬프트·수치 전부 결정
  │
  ├─ Step 2: ComfyUIClient.upload_image()
  │
  ├─ Step 2.5: WanMaskGenerator.generate()
  │    moving_zone bbox → 흑백 마스크 PNG 생성
  │    (SetLatentNoiseMask는 WAN video latent 5D 비호환 → 픽셀 레벨 후처리로 대체)
  │
  └─ Step 3: for attempt in range(1, MAX_RETRIES + 1):
       ├─ _generate_one() → ComfyUI 생성 → mp4 다운로드
       ├─ WanValidator.validate() — 수치 검증 8항목
       ├─ (수치 통과 시) WanAIValidator.validate() — Gemini Vision 영상 검증
       ├─ (AI 통과 시) _apply_post_compositing() → WanBgRemover() → APNG
       │   successful_results.append(result); continue  ← return 대신
       └─ (AI 실패 시) AI 조정값 적용 후 다음 시도
            연속 품질 실패 3회 → analyze_with_exclusion()으로 액션 전환

  루프 종료 후: successful_results[0] 반환 또는 WanResult(success=False)

BG 프롬프트 (전부 중국어 — 항상 강제 추가)

BG_POSITIVE = "纯白色背景，整个动画过程中背景始终保持白色，背景干净无杂质，始终保持恒定的亮度，没有闪烁，画面明亮清晰，边缘锐利，无残影"
    -> 배경과 잔상에 대한 옵션, 깜박임 없음 등
BG_NEGATIVE = "背景变色，背景变暗，背景变黑，背景变灰，背景变黄，背景变紫，背景颜色偏移，非白色背景，黑屏，阴影遮盖，滤镜感，曝光不足，画面闪烁"
    -> 배경색이 변경되는 것을 금지, 필터나 이미지 깜박임 등을 네거티브에 지정

---

[solidSnakesado]

3. 개발 히스토리 (시간순)

---

3-1. 기반 구축 — ComfyUI 연동 + 워크플로우

날짜: 2026-03-06
트랜스크립트: 06-46-00-wan-workflow-api-format-fix, 07-10-58-wan-gui-format-parser

구현 내용

• ComfyUI REST API 연동 (ComfyUIClient) — 이미지 업로드, 워크플로우 실행, 결과 다운로드
• GUI format vs API format 차이 발견
  • ComfyUI WebUI에서 export한 워크플로우는 GUI format (node 위치 정보 포함)
  • API 호출에는 API format 필요 (노드 ID → 입력 매핑 구조)
  • _gui_workflow_to_api() 자동 변환 함수 구현
• 워크플로우를 JSON 파일로 저장하고 로드하는 방식 도입

발생한 문제

• overwrite=true 미설정으로 같은 파일명에 새 이미지 업로드 시 캐시 이미지 사용됨
  • fish 입력 → 개구리 생성 현상 (ComfyUI 이미지 캐시 문제)
  • 수정: 업로드 API에 overwrite: true 파라미터 추가

---

3-2. 최초 테스트 — 물고기 + 화질 문제

날짜: 2026-03-06
트랜스크립트: 08-57-17-comfyui-fish-preprocessing-quality-fix, 09-25-32-wan-i2v-prompt-simplification-loop-fix

발생한 문제: 화질 열화

• 전처리에서 scale=0.65로 이미지를 축소했는데 이것이 PSNR 저하 원인으로 확인됨
• 초기 시스템 프롬프트가 6000자 이상으로 과도하게 복잡 → 모델 혼란

수정 내용

• 프롬프트 6000자 → 2450자로 단순화 (이후에도 계속 개선됨)
• loop_count=1 설정 → 루프 경계 열화 방지 (WAN 내부 루프 설정)
• save_output 파라미터 정리
• PSNR 측정 도구 추가하여 수치 기반 품질 추적 시작

결과

• 단순화 후 생성 품질 개선 확인
• Q4 모델은 VRAM 한계 확인 → Q3_K_S 모델 사용 결정

---

3-3. Validator 구현 + 버그 수정

날짜: 2026-03-06
트랜스크립트: 05-27-01-wan-validator-md-spec-update, 05-43-51-bird-wan-validation-failure-analysis, 10-06-28-wan-i2v-fin-motion-validator-bugs-fix

최초 Validator 구현 (wan_validator.py)

처음 MD 스펙을 기반으로 validator를 구현했으나 스펙과 실제 코드 간 불일치 발견:

• repeated_motion peaks 임계값이 스펙과 달랐음
• return_diff 수치가 다름
• center_drift 항목이 코드에서 누락

수정: MD 스펙 기준으로 validation 로직 재구현

초기 7개 검증 항목

항목	기준
no_motion	char_motion < min_motion * 0.5
too_slow	char_motion < min_motion
too_fast	char_motion > max_motion
repeated_motion	peaks > 8
frame_escape	edge_ratio > 0.08
no_return_to_origin	return_diff > 0.20
center_drift	drift > 0.12

새(bird) 검증 실패 분석 (8회 실패)

bird_with_room.png 8번 실패 분석:

• motion detection 버그: area_contrib 계산으로 오탐
• center_drift false positive 발생
• no_return_to_origin 구조적 문제
• → 당시 fly/wing 특수처리 추가 (이후 제거됨)

물고기 지느러미 모션 문제 (10-06)

• 프롬프트 단순화 후에도 몸통:지느러미 비율 23:1로 악화
• AI 검증에서 no_motion 오판정 발생
• Q3 모델 한계로 미세 지느러미 움직임 생성 어려움 확인
• → 나중에 꼬리 sweep 동작으로 전환 (성공)

---

3-4. 프롬프트 전략 전환 — 영어→중국어

날짜: 2026-03-06
트랜스크립트: 11-52-44-wan-i2v-chinese-prompts-validator-fix

전환 배경

물고기 attempt01~07까지 운동이 거의 없는 영상이 반복됐다. WAN 2.1이 중국어 데이터로 학습된 모델임을 확인 후 프롬프트를 중국어로 전환.

전환 후 효과

• PSNR: 30.0dB → 32.6dB 향상
• 배경 안정성 눈에 띄게 개선

단계적 전환 과정 (4단계)

1단계: positive/negative 프롬프트 중국어 생성 지시 추가 (简体中文으로 작성 강제)

2단계: BG_POSITIVE(배경 흰색 유지 지시) 중국어화 → 배경 안정성 개선

3단계: BG_NEGATIVE(배경 어두워짐 방지)가 영어로 남아있던 것이 새(bird) 테스트에서 배경이 f01부터 RGB 220으로 어두워지는 직접 원인으로 확인 → 중국어화
(이것이 오랫동안 원인을 몰랐던 배경 어두워짐 버그의 근본 원인)

4단계: AI 조정 프롬프트(no_motion 시 수정 지시, return-to-origin 수정 지시 등)도 전부 중국어화

이 세션에서 함께 수정한 내용

• validator /255 버그 발견 및 수정 (아래 3-5 참조)
• AI soft 판정 완화
• 하드코딩 규칙 제거: fish/bird/frog 종류별 분기 코드 제거, Gemini 자유 판단으로 전환
• 5개 스크립트 전체 최종 검증

---

3-5. 개구리 테스트 — 점프 사이클 문제

날짜: 2026-03-06
트랜스크립트: 15-01-30-wan-i2v-validator-fix-frog-motion-issues, 15-59-40-wan-i2v-frog-jump-cycle-prompt-fix, 16-41-07-wan-i2v-frog-jump-validator-240p-fix

Validator /255 이중 적용 버그 (이 세션에서 발견)

증상: attempt0102에서 char_motion=0.0이 반복됨. raw_motion=0.0030.012인데 char_motion=0.0이 나오는 모순.

원인 추적:
_extract_frames가 이미 float32 / 255.0 (01 스케일)로 반환하는데
_calc_character_motion과 _calc_return_diff에서 또 /255를 적용했다.
01 값에 다시 255로 나누면 0~0.004 수준이 되어 threshold(0.04)와 비교 시 항상 no_motion 판정.

수정: 두 함수에서 /255 제거. _get_bg_mask tolerance는 30/255로 변환.
→ 물고기 attempt 통과 확인.

개구리 배/목 호흡 문제

경위: 수치 버그 수정 후에도 개구리가 raw_motion=0.001~0.003으로 완전 정지 영상 반복.
Gemini가 배 호흡, 목 팽창을 반복 선택. Gemini는 产生清晰的像素位移(명확한 픽셀 이동)라고 스스로 합리화.

원인 분석: 배 호흡은 volumetric change(부피 변화)이지 spatial movement(공간 이동)가 아니다.
WAN Q3는 색상/픽셀 이동 없이 미세한 형태 변화만으로는 움직임을 생성하지 못한다.

vision_analyzer 강화: 공간 이동 동작만 선택하도록 3단계 필터 추가:

• Q1. 루프 가능한가
• Q2. 형태가 유지되는가 (핵심) — 움직이는 동안 부위 구조가 변하지 않는가
  • ✅ PASS: 꼬리 sweep, 귀 쫑긋, 머리 기울임, 다리 뻗기
  • ❌ FAIL: 날개 flap(접힘/펼침 구조 변형), 배 호흡, 목 팽창
• Q3. 범위가 10~40% 이내인가

점프 사이클 처리 (3단계 시도)

시도 1 — 제자리 뒷다리 굽힘/펼침:
→ 뒷다리가 몸통 아래 완전히 접혀 화면에서 거의 안 보이는 상태. WAN이 "없는 부위"를 움직이지 못함.

시도 2 — 앞발 움직임:
→ 수치는 통과하지만 AI가 자연스럽지 않다고 판정.

시도 3 — 완전한 점프 사이클:
→ 수직 이동이 center_drift로 탈락.

해결: "강력한 뒷다리를 가진 도약형 생물" SPECIAL CASE 추가.
완전한 점프 사이클 허용 (수직 이동만, 수평 이동 금지).
no_return_to_origin 판정 완화 (0.20 → 0.40).
center_drift를 수평 방향만 체크.

발견된 부작용: 身体完全静止(몸통 완전 정지)를 positive에 쓰면 점프 동작과 모순.
WAN이 혼란을 겪고 아무것도 안 움직이는 영상 생성.
→ positive에서 "몸통 정지" 표현 사용 금지.

240p 테스트

240×240 해상도 테스트 실시. 속도 확인 후 480×480으로 복귀.
속도는 빠르지만 품질이 보장 되지 않음,
현재 사용중인 Wan-AI/Wan2.1-I2V-14B-480P를 GGUF 포맷으로 직접 변환한 모델 파일(wan2.1-i2v-14b-480p-Q3_K_S.gguf) 사용
wan2.1 - WAN 버전 2.1
i2v - Image-to-Video (이미지→영상)
14b - 파라미터 140억개
480p - 480P 해상도용으로 학습된 모델
Q3_K_S - 3비트 양자화 (Small 변형)
.gguf - GGUF 포맷 (ComfyUI-GGUF 노드로 로드)

480P 해상도에 최적화 되어 있음

3-6. pingpong 도입 + AI Validator 비디오 직접 피드

날짜: 2026-03-06
트랜스크립트: 18-45-41-wan-i2v-pingpong-validator-fix, 18-59-50-wan-i2v-ai-validator-video-direct-feed

pingpong 도입

경위: 단순 loop 방식에서 영상 끝→시작 이음새가 튀는 현상 발생.

해결: pingpong=True — 순방향 재생 후 역방향 재생. 이음새 자연스럽게 연결.

pingpong에서 발생한 AI Validator 오판정:
pingpong 구조에서 MIDDLE(50%)이 FIRST(0%)와 유사한 것은 정상이다.
AI validator가 이 구조를 몰랐을 때 MIDDLE이 FIRST와 비슷하다는 이유로 no_motion 오탐.

수정: AI validator에 pingpong 구조 명시, 모션 판단은 반드시 FIRST vs QUARTER(25%) 비교로.

분류 기반 코드 전체 제거 (이 세션)

is_jump, is_fly, is_swim 분류 플래그 전체 제거.
통일된 기준 적용 — 모든 캐릭터에 동일한 검증.
특정 모션에 종속된 분류 플래그 값 제거

AI Validator: 프레임 추출 → 비디오 직접 전달

이전 방식: mp4에서 3프레임 추출 → Gemini에게 이미지 전달
문제: Gemini가 정지 이미지로 모션을 판단하기 어려움

수정: mp4 파일 자체를 base64로 인코딩 → Gemini에게 직접 전달
원본 이미지(스프라이트) + mp4 함께 전달
→ Gemini가 실제 영상을 보고 모션 품질 직접 판단 가능

개구리 attempt07 최고 품질 달성

비디오 직접 피드 적용 후 개구리 점프 attempt07이 최고 품질로 확인.
이후 AI 조정 누적으로 품질 저하 발생 → 조정 누적 문제 확인.

---

3-7. 물고기 APNG 완성 + frame_escape 오판정 수정

날짜: 2026-03-07
트랜스크립트: 06-07-49-wan-i2v-fish-motion-analysis, 09-01-12-wan-i2v-fish-apng-fixes

frame_escape 오판정 — 노란 필터 문제

증상: 물고기 attempt01~03에서 frame_escape로 반복 실패. 실제로는 프레임 밖으로 나가지 않음.

원인: WAN이 생성한 영상의 배경에 노란 필터가 생기면서 배경 diff가 0.19까지 올라감.
_calc_edge_ratio의 tolerance가 0.15여서 배경 픽셀 전체가 "비배경"으로 인식 → edge_ratio=1.0.

수정: tolerance 0.15 → 0.25

pingpong 이음새 validator 버그

pingpong 영상의 마지막 프레임이 시작과 유사 → no_return_to_origin 오탐
pingpong 구조를 validator에서도 인식하도록 수정

no_motion seed 재시도 로직 추가

no_motion 판정 시 같은 프롬프트로 seed 변경해 재시도하는 옵션 추가
(단순 운이 나쁜 경우와 실제 생성 불가 경우를 구분)

AI Validator 중국어 프롬프트 수정

AI 검증 결과 전달에 사용되는 내부 텍스트도 중국어로 통일

APNG disposal=2 수정

disposal=2: 각 프레임 후 투명으로 초기화
→ 브라우저에서 APNG 재생 시 이전 프레임 잔상 방지

WanBgRemover tolerance 조정

증상: 물고기 APNG에서 배경 회색 잔상이 남는 현상.

원인: WAN이 생성한 배경이 실제로는 흰색(255)이 아니라 회색(RGB 206217)으로 나오는 경우.
tolerance=35이면 diff(255-206)=49 > 35이 되어 배경 픽셀이 제거 안 됨.

수정: tolerance=35 → 50

APNG 뷰어 HTML 생성

생성된 APNG를 확인하기 위한 debug_viewer.html 생성

---

3-8. 새(bird) 테스트 — BG 문제 + 날개 flap 10회 실패

날짜: 2026-03-07
트랜스크립트: 10-35-10-wan-i2v-bird-bg-fix-session, 11-38-40-wan-i2v-bird-motion-quality-session

배경 어두워짐 문제 (BG_NEGATIVE 영어 잔존)

증상: 새 테스트에서 attempt01, 06, 07, 08이 배경이 f01부터 RGB 220으로 어두워짐.

원인 발견: BG_NEGATIVE가 영어로 남아있었음.

# 영어 상태 (버그):
BG_NEGATIVE = "dark background, gray background..."

# 수정 후 (중국어):
BG_NEGATIVE = "背景变色，背景变暗，背景变黑，背景变灰..."

이것이 배경 어두워짐의 직접 원인이었음. 중국어로 변환 후 해결.

positive 누적 제한 추가

AI가 매 attempt마다 positive에 내용을 append → attempt07에서 300자 초과
서로 충돌하는 지시가 생기기 시작
→ positive 150자 초과 시 초기값 + 새 조정으로 리셋 규칙 추가

날개 flap 10회 실패 분석

새 테스트에서 날개 flap을 10회 이상 시도했지만 전부 실패.

실패 원인 분석:

캐릭터	동작	결과	이유
물고기	꼬리 sweep	✅ 성공	꼬리 형태 유지하며 위치만 이동
개구리	점프	✅ 성공	전체가 rigid unit으로 이동
새	날개 flap	❌ 10회+ 실패	날개가 접히고 펼쳐지면서 형태 자체가 변형

날개 flap은 3D 구조 변형(접힘/펼침)을 동반한다.
2D 픽셀 기반 모델(WAN Q3)이 날개의 3D 구조 변형을 텍스처 일관성 있게 생성하는 것은 근본적으로 어렵다.

결정: 날개 flap 시도 완전 포기.
전략 전환: "LOWEST DIFFICULTY(가장 쉬운 것)" → "MOST NATURAL motion(가장 자연스러운 것) + WAN 생성 가능성 필터"

AI Validator 판정 기준 범용화:

• 초기: wing/fin/feathers 예시가 박혀 있어서 새/물고기에만 적용한다고 오해 가능
• 수정: 모두 the moving part / fixed parts로 추상화 → 어떤 모션에도 동일 적용

5가지 실패 패턴 명문화:
새 attempt07에서 AI가 "성공"이라고 인정하면서도 FAIL을 낸 사례 발생.
Gemini에게 직접 영상을 분석시켜 지적된 내용을 기준으로 추가:

• FLICKERING: 움직이는 부위가 부드러운 호 대신 프레임마다 급격히 다른 형태로 튀는 경우
• GHOSTING: 이전 프레임 이미지가 모션 경로를 따라 블리딩
• TEXTURE RECONSTRUCTION: 텍스처(깃털/비늘 등)가 매 프레임 재생성
• PART INDEPENDENCE: 고정되어야 할 부위의 형태·텍스처가 변형 (1~2px 미세 진동은 PASS)
• INCOHERENT MOTION RHYTHM: pendulum/sine curve가 아닌 랜덤 가속/감속으로 떨리는 느낌

vision_analyzer STEP 2~6 전면 범용화:

• 새/물고기/개구리 특수처리 제거
• 어떤 이미지든 동일한 VISION_SYSTEM_PROMPT 적용
• 계속 동일한 이미지를 사용하다 보니 계속, 새/물고기/개구리의 이미지에만 특화된 기능들이 추가되는 문제로 범용적으로 사용할 수 있게 제거 처리

---

3-9. 마스킹 파이프라인 도입 + 후처리 합성 전환

날짜: 2026-03-07
트랜스크립트: 12-46-23-wan-i2v-masking-pipeline-session, 13-57-11-wan-i2v-masking-postcomp-session

WanMaskGenerator 신규 구현

목적: moving_zone(움직이는 부위의 bbox)에만 WAN 모션을 적용하고 나머지는 원본 이미지를 유지
구현: moving_zone bbox → 흑백 마스크 PNG 생성

• 전체 흰색 = fixed (원본 유지)
• moving zone = 검정 (WAN 생성 사용)
• 경계: GaussianBlur (이미지 크기의 3%) → 자연스러운 경계

SetLatentNoiseMask 비호환 발견

SetLatentNoiseMask 노드로 마스크를 WAN에 직접 주입 시도 → 실패

원인: WAN은 video latent(5D 텐서: batch × channels × frames × height × width)를 사용하는데
SetLatentNoiseMask는 이미지 latent(4D: batch × channels × height × width)를 기대한다.
차원 불일치로 실행 자체가 안 됨.

전환 결정: 마스크를 ComfyUI 내부에서 사용하지 않고, 후처리 합성(Post-Compositing) 방식으로 변경.

_apply_post_compositing() 구현

# 픽셀 레벨 합성: 마스크 기반으로 WAN 생성 프레임과 원본 이미지 합성
# 흰색 마스크 영역: 원본 이미지 유지
# 검정 마스크 영역: WAN 생성 프레임 사용
composited = mask * original + (1-mask) * generated

→ 고정 부위는 픽셀 레벨에서 원본을 그대로 사용하므로 ghosting/flickering 원천 차단

이전 세션의 fly 특수처리 제거 (이 세션)

fly 관련 특수처리 코드 제거, SOFT_ISSUES 재정리

---

3-10. 합성 순서 버그 + 액션 전환 로직 추가

날짜: 2026-03-08
트랜스크립트: 03-16-51-wan-i2v-compositing-motion-fix, 04-06-53-wan-i2v-validator-action-switch-manual

합성→검증 순서 버그 발견

버그: _apply_post_compositing()를 수치 검증 전에 실행하고 있었음.

문제: 합성된 영상은 원본 정보가 반영되어 수치 검증 결과가 왜곡됨.
실제 WAN이 생성한 모션을 수치로 측정해야 하는데 합성 후 측정하면 오탐.

수정: 검증(수치 + AI) → 통과 후 합성 순서로 변경.

# 수정 전 (버그):
composited = _apply_post_compositing(raw_video)
result = validate(composited)

# 수정 후 (정상):
result = validate(raw_video)
if result.passed:
    final = _apply_post_compositing(raw_video)

vision_analyzer: identity motion 우선 선택

동작 선택 시 가장 자연스러운 "IDENTITY MOTION" 을 우선시하는 방식으로 전환.

연속 품질 실패 시 액션 전환 로직 추가

문제: 특정 동작(예: 날개 flap)이 반복 실패할 때 같은 동작만 계속 재시도함.

수정: 연속 품질 실패 3회 → analyze_with_exclusion() 호출
→ 실패한 액션을 명시하고 다른 동작을 선택하도록 요청

def analyze_with_exclusion(self, image, excluded_actions: list[str]):
    # excluded_actions를 명시하여 다른 동작 선택 강제
    # temperature=0.5 (약간 창의적으로)

수동 선택 영상 처리 메서드 추가

process_manual_selection(video_path) — 특정 attempt 결과를 수동으로 선택해 후처리하는 메서드

---

3-11. 수치 검증 대규모 오탐 수정

날짜: 2026-03-08
트랜스크립트: 05-22-26-wan-i2v-validator-frame-quality-fixes, 06-37-57-wan-i2v-validator-bg-fix-session, 08-27-12-wan-i2v-validator-generality-fix

area_contrib 제거

기존 area_contrib 계산이 오탐의 원인이었음 → 제거.

peaks 상향

repeated_motion peaks 임계값: 8 → 12 (pingpong 기준으로 상향)
pingpong 영상에서는 자연스럽게 peaks가 높아지기 때문.

too_fast AND 조건 추가

# 수정 전:
too_fast = char_motion > max_motion

# 수정 후 (오탐 방지):
too_fast = char_motion > max_motion AND raw_motion > min_motion * 0.5

raw_motion 교차 검증으로 빠른 배경 변화를 캐릭터 모션으로 오탐하는 경우 방지.

frame_count 동적 결정 도입

기존: 고정 frame_count
변경: Vision Analyzer가 SHORT/MEDIUM/LONG 중 선택

• SHORT: 17~21 프레임
• MEDIUM: 25~33 프레임
• LONG: 33~49 프레임

AI Validator 신체 소실/회색 박스 감지 강화 (05:22)

영상에서 캐릭터가 사라지거나 회색 박스로 대체되는 경우 감지 추가

JSON 파싱 복구 3단계

Gemini 응답에서 JSON 파싱 오류 발생:

1단계: 정상 파싱
2단계: reason 필드 제거 후 재파싱 (reason에 따옴표가 들어있는 경우)
3단계: passed/issues 필드만 regex 추출

bg_drift 단위 버그 수정

배경 drift 계산에서 단위 변환 버그 발견 및 수정.

frame_escape 오탐 방지

기존 frame_escape 로직이 배경 변색을 이탈로 오탐하는 추가 케이스 발견 및 수정.

AI 판정 기준 완화

• no_motion 판정 기준 완화 (수치 validator 통과 후 AI도 no_motion 이중 판정 방지)
• unnatural_movement 판정 완화
• SOFT_ISSUES 확장

White Anchor 전처리 추가

_white_anchor() 함수 추가:

• 배경 순백색 강제 (RGB 255,255,255)
• 경계 픽셀 선명화
• 검정 배경 이미지도 흰 배경으로 자동 변환 → 별도 처리 불필요

배경만 변색 시 통과 로직

AI validator:

• Category A (배경만 변색, 캐릭터 정상): PASS — bg_remover가 후처리로 제거
• Category B (전체 밝기 이동, 캐릭터도 어두워짐): FAIL

범용성 검토 완료

모든 검증 로직이 물고기/새/개구리 이외 이미지에도 적용 가능한지 검토 완료.

---

3-12. Ghosting 감지 강화 + 프롬프트 누적 제거

날짜: 2026-03-08
트랜스크립트: 14-14-05-wan-i2v-ghosting-motion-fix

GHOSTING을 AI Validator 최상단으로 이동

경위: ghosting이 발생한 영상이 다른 항목 검사 중간에 통과하는 경우 발생.

수정:

[이전 순서]
1. SPEED
2. RETURN TO ORIGIN
3. FRAME ESCAPE
4. NATURALNESS (GHOSTING 포함)
5. CHARACTER CONSISTENCY

[수정 후 순서]
1. GHOSTING (ZERO TOLERANCE — check this FIRST)  ← 최상단 이동
2. SPEED
3. RETURN TO ORIGIN
...

GHOSTING 두 형태 명시:

• Form 1 (OUTLINE GHOST): 움직이는 부위 윤곽에 반투명 잔상
• Form 2 (BODY DRIFT GHOST): 고정 몸통이 미세하게 이동하며 두 개로 겹쳐 보임
• 고정 몸통이 soft/translucent/doubled이면 무조건 FAIL

ghost_score 수치 메트릭 추가 (wan_validator.py)

GHOST_THRESHOLD = 0.005  # 0.5%

def _calc_ghost_score(self, frames, bg_mask):
    """
    첫 프레임 배경 픽셀 위치에 이후 프레임에서
    캐릭터 평균색과 80/255 이내 픽셀이 나타나는 비율
    """
    # 첫 프레임 배경 픽셀 위치 기억
    # 이후 프레임에서 해당 위치에 캐릭터 색상 출현 비율 계산
    # 0.5% 이상 = ghosting FAIL

프롬프트 누적 방지 규칙 강화

최악의 사례:
后腿轻轻弯曲和伸展(뒷다리 살살 굽힘)이 positive에 쓰인 후,
AI 조정 과정에서 이 표현을 negative에도 추가.
결과: 뒷다리 굽힘 동작 자체가 억제되어 완전 정지 영상 생성.

규칙 추가:

• positive 150자 초과 시 초기값 + 새 조정으로 리셋
• negative 200자 초과 시 동일하게 리셋
• STEP G: positive에서 쓴 표현을 negative에 절대 복사 금지

Negative 우선 원칙 확립

발견: WAN 특성상 positive로 동작을 유도하는 것보다 negative로 원치 않는 동작을 막는 것이 더 직접적이고 효과적이다.

적용: naturalness/character 이슈의 조정은 NEGATIVE IS PRIMARY로 명시.
positive는 보조 수단.

Vision Analyzer: MOST NATURAL motion 방향 전환

• "LOWEST DIFFICULTY" 표현 삭제
• "MOST NATURAL motion that WAN can generate" 로 변경
• 날개 운동 우선 (새), 10~40% 가시범위 강제

---

3-13. 암전 방지 + SOFT_ISSUES 수정 + 테스트 캐릭터 생성

날짜: 2026-03-08
트랜스크립트: 16-31-16-wan-i2v-ghosting-blackout-test-chars

암전/필터 방지 BG 프롬프트 강화

기존 BG_POSITIVE/NEGATIVE에 암전 관련 키워드 추가:

# BG_POSITIVE에 추가:
"始终保持恒定的亮度，没有闪烁，画面明亮清晰，边缘锐利，无残影"

# BG_NEGATIVE에 추가:
"背景变灰，背景变黄，背景变紫，非白色背景，黑屏，阴影遮盖，滤镜感，曝光不足，画面闪烁"

SOFT_ISSUES에서 no_motion 제거

이전: SOFT_ISSUES = {"background_color_change", "no_motion"}
→ 수치 validator 통과 후 AI가 no_motion만 판정하면 PASS로 처리했음

문제: AI가 no_motion을 판정한다는 것은 육안으로도 정지처럼 보인다는 의미.
이런 영상을 PASS시키면 실제로 움직이지 않는 영상이 최종 결과물이 됨.

수정: SOFT_ISSUES = {"background_color_change"}
background_color_change만 soft인 이유: bg_remover가 후처리로 배경을 제거하기 때문.

MAX_RETRIES=5로 임시 변경

테스트 속도를 위해 10 → 5 임시 변경. 운영 시 반드시 10으로 복구 필요.

---

3-14. successful_results 루프 수정 + 이미지 분리

날짜: 2026-03-08
트랜스크립트: 17-45-39-wan-i2v-allretries-charcrops-session, 17-47-22-wan-i2v-sprite-split-allretries-handoff, 17-48-57-wan-i2v-backend-retries-code-summary

wan_backend.py: successful_results 루프 수정 (핵심 수정)

문제:

# 버그: 성공 즉시 return → 첫 성공에서 루프 완전 종료
if ai_result.passed:
    return WanResult(success=True, ...)

의도: MAX_RETRIES 횟수 전부를 생성하여 나중에 비교/선택 가능하게 한다.

수정 (3곳):

# ① 루프 시작 전 (약 1160번 줄) — 리스트 초기화
successful_results: list[WanResult] = []

# ② 성공 시 return → continue 변경 (약 1257~1272번 줄)
# 수정 전:
return WanResult(success=True, video_path=apng_path, ...)

# 수정 후:
successful_results.append(WanResult(success=True, video_path=apng_path, ...))
continue

# ③ 루프 종료 후 (약 1468~1476번 줄) — 첫 성공 반환
if successful_results:
    return successful_results[0]
return WanResult(success=False, analysis=analysis, attempts=MAX_RETRIES)

→ 모든 attempt를 생성하고, 성공한 결과들 중 첫 번째를 반환.

---

[solidSnakesado]

4. 검증 시스템 발전 과정

수치 Validator (wan_validator.py) 진화

시점	변경 내용
초기	7개 항목 구현 (no_motion, too_slow, too_fast, repeated_motion, frame_escape, no_return_to_origin, center_drift)
03-06	/255 이중 적용 버그 수정 → 물고기 통과
03-06	frame_escape tolerance 0.15 → 0.25 (노란 필터 오탐 방지)
03-06	점프 생물 no_return_to_origin 완화 (0.20 → 0.40)
03-06	center_drift 수평만 체크 (점프 생물 수직 이동 허용)
03-07	pingpong 이음새 validator 버그 수정
03-08	area_contrib 제거
03-08	peaks 8 → 12 (pingpong 기준)
03-08	too_fast AND 조건 추가
03-08	frame_count 동적 결정
03-08	bg_drift 단위 버그 수정
03-08	ghost_score 신규 추가 (GHOST_THRESHOLD=0.005)
03-08	배경색 자동 감지 (첫 프레임 테두리 픽셀 평균)

AI Validator (wan_ai_validator.py) 진화

시점	변경 내용
초기	프레임 추출 (3장) → Gemini 전달
03-06	mp4 직접 전달로 전환 (원본 이미지 + 영상)
03-06	pingpong 구조 명시 (MIDDLE ≈ FIRST는 정상)
03-06	분류 기반 코드 (is_jump/fly/swim) 전체 제거
03-07	5가지 실패 패턴 명문화 (FLICKERING/GHOSTING/TEXTURE RECONSTRUCTION/PART INDEPENDENCE/INCOHERENT MOTION RHYTHM)
03-07	판정 기준 범용화 (the moving part/fixed parts로 추상화)
03-08	신체 소실/회색 박스 감지 추가
03-08	JSON 파싱 복구 3단계 추가
03-08	AI 판정 기준 완화 (no_motion, unnatural_movement)
03-08	GHOSTING ZERO TOLERANCE 최상단 이동
03-08	Form 1 (OUTLINE GHOST) + Form 2 (BODY DRIFT GHOST) 명시
03-08	Background color: Category A/B 구분 (A는 PASS)

현재 수치 Validator 8항목

no_motion         char_motion < min_motion * 0.5
too_slow          char_motion < min_motion
too_fast          char_motion > max_motion AND raw_motion > min_motion*0.5
repeated_motion   peaks > 12 (pingpong 기준)
frame_escape      edge_ratio > 0.08, tolerance=0.25
no_return_to_origin  return_diff > 0.40
center_drift      drift > 0.12
ghosting          ghost_score > 0.005

---

[solidSnakesado]

5. 프롬프트 개선 과정

Vision Analyzer (wan_vision_analyzer.py) 프롬프트 진화

시점	변경 내용
초기	6000자 복잡한 시스템 프롬프트
03-06	6000자 → 2450자 단순화
03-06	영어 → 중국어 전환 (positive/negative)
03-06	MOVING PART ISOLATION 원칙 추가
03-06	배 호흡/목 팽창 금지 (volumetric vs spatial 구분)
03-06	3단계 WAN 필터 추가 (Q1 루프/Q2 형태 유지/Q3 범위)
03-06	점프 생물 SPECIAL CASE 추가
03-06	positive에서 "몸통 정지" 표현 금지
03-07	분류 기반 특수처리 전체 제거
03-07	STEP 2~6 전면 범용화
03-07	moving_zone bbox 추가 (마스크 생성용)
03-08	identity motion 우선 선택
03-08	"LOWEST DIFFICULTY" → "MOST NATURAL motion + WAN 필터"
03-08	analyze_with_exclusion() 추가

AI 조정 프롬프트 누적 방지 (wan_backend.py)

문제의 발전 과정:

1. 매 attempt마다 AI가 positive/negative에 내용 append
2. attempt07에서 positive 300자 초과
3. 서로 충돌하는 지시 발생
4. 최악 사례: positive 표현이 negative에 복사 → 동작 자체 억제

최종 규칙:

# positive 150자 초과 시 리셋
if len(current_positive) > 150:
    current_positive = initial_positive + new_adjustment

# negative 200자 초과 시 리셋
if len(current_negative) > 200:
    current_negative = initial_negative + new_adjustment

# STEP G: positive 표현을 negative에 절대 복사 금지

현재 VISION_SYSTEM_PROMPT 단계 (완성본)

STEP 1: IDENTIFY THE SUBJECT — 외형·색상·부위
STEP 2: CHOOSE THE ACTION — MOST NATURAL motion + 3단계 WAN 필터
         Q1. 루프 가능한가
         Q2. 형태가 유지되는가 (핵심)
         Q3. 범위가 10~40% 이내인가
         SPECIAL CASES: 도약형 생물 → 완전한 점프 사이클 + 수직 이동만
STEP 3: ISOLATE MOVING PARTS — 최소 부위, 나머지 전신 고정
STEP 4: MOVING ZONE BBOX — 상대좌표 [x1,y1,x2,y2], 20% 여유
STEP 5: FRAME RATE — 8~24fps
STEP 6: WRITE PROMPTS — 중국어. positive 60단어 이내, negative 40단어 이내
STEP 7: MOTION THRESHOLDS — min_motion·max_motion·max_diff
STEP 8: FRAME COUNT — SHORT 17~21 / MEDIUM 25~33 / LONG 33~49

금지 단어 (whole-body 회전/이동 유발)

旋转, 转身, 扭动, 摇摆身体, 全身运动

---

[solidSnakesado]

6. 핵심 설계 결정 배경 (Why)

6-1. 영어 → 중국어 프롬프트

WAN 2.1은 중국어 데이터로 학습된 모델. PSNR 30.0dB → 32.6dB 향상. BG_NEGATIVE가 영어로 남아있던 것이 배경 어두워짐(RGB 220)의 직접 원인이었음.

6-2. steps=30 → 20

생성 시간 33% 단축. frames는 줄이면 pingpong 복귀 문제 악화 → 유지.

6-3. pingpong=True

이음새 완화. MIDDLE(50%)이 FIRST(0%)와 유사한 것은 정상.

6-4. 하드코딩 분기 제거

fish/bird/frog 분기 → 미지 이미지 대응 불가. 전체 제거, Gemini 자유 판단.

6-5. 배 호흡·목 팽창 금지

volumetric change는 WAN 생성 불가. spatial movement만 허용.

6-6. 새 날개 flap 10회 실패 → 저난이도 원칙

날개 flap은 3D 구조 변형 동반 → 2D 픽셀 모델 생성 불가. "MOST NATURAL + WAN 생성 가능성 필터" 원칙.

6-7. 개구리 점프 처리

뒷다리 굽힘(보이지 않음) → 앞발(부자연스러움) → 완전한 점프 사이클. 몸통 정지 표현이 점프와 모순 → positive에서 금지.

6-8. AI 조정 누적 문제

positive 표현이 negative에 복사되어 동작 억제. positive 150자/negative 200자 초과 시 리셋. STEP G: positive 표현 negative 복사 절대 금지.

6-9. Negative 우선 원칙

WAN은 positive 유도보다 negative 차단이 더 효과적. naturalness/character 이슈 = NEGATIVE IS PRIMARY.

6-10. Validator /255 이중 적용 버그

_extract_frames가 이미 0~1 스케일 반환 → 두 함수에서 또 /255 적용 → char_motion=0.0 오판정. 제거.

6-11. frame_escape tolerance 오탐

배경 노란 필터(diff~0.19) > tolerance(0.15) → 날개 이탈로 오탐. 0.15 → 0.25.

6-12. WanBgRemover tolerance=50

WAN 생성 배경이 회색(206~217)으로 나오는 경우. tolerance=35이면 diff=49>35로 제거 안 됨. → 50.

6-13. GHOSTING 최상단 이동

Ghosting 발생 영상이 다른 항목 검사 중 통과. ZERO TOLERANCE — 가장 먼저. 수치에도 ghost_score 추가.

6-14. 5가지 실패 패턴 명문화

AI가 "성공"이라고 인정하면서도 FAIL. Gemini가 직접 지적한 내용을 기준으로 추가. the moving part/fixed parts로 추상화.

6-15. SOFT_ISSUES에서 no_motion 제거

AI no_motion = 육안으로도 정지처럼 보임. SOFT_ISSUES = {"background_color_change"}만 유지.

6-16. successful_results 루프 수정

성공 즉시 return → 첫 성공에서 루프 종료. 수정: return → append + continue. 모든 attempt 생성 후 첫 번째 성공 반환.

6-17. SetLatentNoiseMask 비호환 → 후처리 합성

WAN video latent는 5D 텐서. SetLatentNoiseMask는 4D 기대 → 차원 불일치로 실패. 픽셀 레벨 후처리 합성으로 전환.

6-18. 합성→검증 순서 버그

합성된 영상으로 수치 측정 → 원본 모션 왜곡됨. 검증 먼저, 통과 후 합성으로 순서 변경.

---

[solidSnakesado]

7. 1주차 최종 파일 현황

스크립트 파일 (6개)

로컬 경로: ~/anim_pipeline/image_pipeline/sprite_gen/

파일	줄수	역할
wan_backend.py	1687	메인 오케스트레이터. 전체 흐름 제어
wan_ai_validator.py	541	Gemini Vision으로 영상 품질 검증
wan_vision_analyzer.py	436	Gemini Vision으로 이미지 분석 + 프롬프트/수치 결정
wan_validator.py	708	수치 기반 8항목 검증
wan_mask_generator.py	104	moving_zone → 흑백 마스크 PNG
wan_bg_remover.py	209	flood fill 배경 제거 → APNG

---

8. PENDING

• 🔴 최우선: wan_backend.py 60번 줄 MAX_RETRIES = 5 → 10 복구
• 🟡 successful_results 수정 후 실제 동작 확인 (elephant 테스트)
• 🟢 characters2/ + vehicles/ 40개 이미지 파이프라인 일괄 실행
• 🟢 cartoon_animals/ 10개 파이프라인 실행

파이프라인 실행 방법

# 터미널 1 — ComfyUI
cd ~/ComfyUI && source venv/bin/activate && python main.py --listen

# 터미널 2 — 파이프라인
cd ~/anim_pipeline && source animVenv/bin/activate
python3 -c "
import os, logging
logging.basicConfig(level=logging.INFO)
from dotenv import load_dotenv; load_dotenv()
from image_pipeline.sprite_gen.wan_backend import WanBackend
backend = WanBackend(
    api_key=os.environ['GEMINI_API_KEY'],
    comfyui_url='http://127.0.0.1:8188',
    output_dir='outputs/wan',
)
backend.generate('/home/sado/ComfyUI/input/16_elephant.png')
"

---

[solidSnakesado]

1주차 성능·품질 향상 히스토리

기간: 2026-03-06 ~ 2026-03-08 (1주차)
정리 기준: 각 처리가 성능 또는 품질에 미친 구체적 영향

---

1. 화질 / 생성 품질 향상

1-1. 프롬프트 언어 전환: 영어 → 중국어

항목	변경 전	변경 후	개선폭
PSNR	30.0 dB	32.6 dB	+2.6 dB (8.7% 향상)
배경 안정성	RGB 220까지 어두워짐	흰색 유지	배경 변색 근본 해결
모션 반응성	attempt 01~07 정지 영상 반복	1~3회 내 모션 생성	모션 생성 성공률 대폭 향상

WAN 2.1이 중국어 데이터로 학습된 모델이라는 점이 핵심. 4단계에 걸쳐 순차 전환: positive/negative → BG_POSITIVE → BG_NEGATIVE(이것이 배경 어두워짐의 직접 원인이었음) → AI 조정 프롬프트.

1-2. 프롬프트 단순화: 6000자 → 2450자

항목	변경 전	변경 후
시스템 프롬프트 크기	6000자+	2450자
생성 품질	모델 혼란으로 불안정	일관된 출력

과도하게 복잡한 지시가 WAN 모델에 혼란을 야기했으며, 단순화 후 생성 안정성이 개선됨.

1-3. steps 감소: 30 → 20

항목	변경 전	변경 후	개선폭
생성 시간	기준값	기준 × 0.67	33% 단축
품질	기준값	체감 차이 없음	유지

frames를 줄이면 pingpong 복귀 문제가 악화되므로 steps만 감소.

1-4. pingpong 도입

항목	변경 전 (단순 loop)	변경 후 (pingpong)
이음새 품질	끝→시작에서 튀는 현상	순방향→역방향으로 자연스러운 연결
루프 자연스러움	눈에 띄는 끊김	매끄러운 루프

1-5. White Anchor 전처리 도입

항목	변경 전	변경 후
배경색	유사 흰색 (248~252 등)	정확한 순백 RGB(255,255,255)
캐릭터 경계	흐릿한 전환	UnsharpMask로 선명화
WAN latent 안정성	배경 latent 불일치 → 변색 유발	일관된 latent 매핑

검정 배경 이미지도 자동으로 흰 배경으로 변환 처리.

---

2. 검증 정확도 향상 (오탐/미탐 제거)

2-1. /255 이중 적용 버그 수정

항목	버그 상태	수정 후	영향
char_motion	항상 0.0 (no_motion 판정)	정상 수치 출력	모든 영상이 no_motion으로 거부되던 문제 해결

_extract_frames가 이미 01 스케일로 반환하는데 _calc_character_motion에서 또 /255 적용. 01 값에 /255하면 0~0.004가 되어 threshold(0.04)보다 항상 낮음.

2-2. frame_escape tolerance 조정: 0.15 → 0.25

항목	변경 전	변경 후	영향
배경 노란 필터 오탐	diff 0.19 > 0.15 → 이탈로 오탐	diff 0.19 < 0.25 → 정상 통과	배경 변색을 이탈로 오인하는 문제 해결

실제 캐릭터 이탈은 diff > 0.25이므로 탐지 능력은 유지.

2-3. area_contrib 제거

항목	변경 전	변경 후	영향
char_motion 계산	색상 diff + 면적 변화율 합산	색상 diff만 사용	날개 접힘 등 면적 급변 시 5~20배 부풀려지던 too_fast 오탐 제거

면적 변화율(area_rate)이 1.0 이상으로 폭발하여 char_motion을 왜곡하던 문제.

2-4. too_fast 조건: OR → AND 교차검증

항목	변경 전	변경 후
판정 조건	char_motion > max (단일)	char_motion > max AND raw_motion > min*0.5
오탐률	면적 변화만으로 too_fast 판정	raw_motion이 낮으면 실제 빠른 것이 아님으로 통과

2-5. peaks 임계값 상향: 8 → 12

항목	변경 전	변경 후	영향
repeated_motion 기준	peaks > 8	peaks > 12	pingpong 64프레임에서 자연스러운 피크를 오탐하지 않음

2-6. no_return_to_origin 완화: 0.20 → 0.40

항목	변경 전	변경 후	영향
복귀 허용 오차	return_diff > 0.20 실패	return_diff > 0.40 실패	pingpong 이음새 + 점프 사이클에서 오탐 방지

2-7. center_drift 수평만 체크

항목	변경 전	변경 후	영향
drift 방향	수직+수평 모두	수평 drift만 측정	점프 동작의 수직 이동이 drift로 오탐되는 문제 해결

2-8. ghost_score 신규 추가

항목	변경 전	변경 후	영향
Ghosting 감지	AI 판정에만 의존	수치 메트릭(0.5% 임계) + AI 이중 감지	잔상 영상이 다른 항목 검사 중 통과하는 케이스 차단

2-9. bg_drift → char_brightness_drift 교차 판정

항목	변경 전	변경 후	영향
배경 변색 판정	bg_drift > 30이면 무조건 FAIL	캐릭터 밝기도 변했으면 FAIL, 배경만 변했으면 PASS	bg_remover로 해결 가능한 케이스를 불필요하게 거부하지 않음

2-10. frame_escape에 bg_drift 억제 추가

항목	변경 전	변경 후	영향
edge_ratio 높음	무조건 frame_escape	bg_drift > 30이면 배경 변색 오탐으로 억제	배경 변색이 이탈로 이중 판정되는 문제 제거

---

3. AI Validator 품질 향상

3-1. 프레임 추출 → mp4 직접 전달

항목	변경 전	변경 후	영향
Gemini 입력	3장의 정지 프레임	mp4 영상 파일 전체	Gemini가 실제 모션을 보고 판단 가능

정지 이미지로는 모션 품질 판단이 근본적으로 불가능했음.

3-2. pingpong 구조 명시

항목	변경 전	변경 후	영향
AI 판단 기준	FIRST vs MIDDLE 비교	FIRST vs QUARTER(25%) 비교	pingpong에서 MIDDLE≈FIRST를 no_motion으로 오탐하던 문제 해결

3-3. GHOSTING ZERO TOLERANCE 최상단 이동

항목	변경 전	변경 후	영향
Ghosting 검사 순서	NATURALNESS 하위 항목	가장 먼저 검사 (ZERO TOLERANCE)	Ghosting 영상이 다른 항목 통과하는 케이스 완전 차단

3-4. 5가지 실패 패턴 명문화

항목	변경 전	변경 후
AI 판정 기준	"자연스러운가" 주관적 판단	FLICKERING / GHOSTING / TEXTURE RECONSTRUCTION / PART INDEPENDENCE / INCOHERENT MOTION RHYTHM 5가지 구체적 패턴
일관성	Gemini 응답마다 판정 기준 변동	명확한 패턴 매칭으로 일관된 판정

3-5. SOFT_ISSUES에서 no_motion 제거

항목	변경 전	변경 후	영향
SOFT_ISSUES	{background_color_change, no_motion}	{background_color_change} 만	육안으로 정지처럼 보이는 영상이 PASS되는 문제 제거

3-6. JSON 파싱 3단계 복구

항목	변경 전	변경 후	영향
Gemini JSON 파싱	1단계만 (정상 파싱)	3단계 (정상 → reason 제거 → regex 최소 추출)	Gemini 응답 포맷 오류 시에도 판정 결과 추출 가능

3-7. Category A/B 배경 변색 구분

항목	변경 전	변경 후	영향
배경 변색 판정	무조건 FAIL	A(배경만): PASS, B(전체): FAIL	bg_remover로 해결 가능한 배경 변색을 불필요하게 거부하지 않음

---

4. 마스킹 / 후처리 합성

4-1. 후처리 합성 도입

항목	변경 전	변경 후	영향
고정 부위 처리	WAN이 전체 이미지를 자유 생성	고정 부위는 원본 픽셀 그대로 덮어씌움	고정 부위의 ghosting/flickering 원천 차단

SetLatentNoiseMask가 WAN video latent(5D)와 비호환이라 ComfyUI 내부 마스킹 대신 픽셀 레벨 후처리로 전환.

4-2. 합성 순서 수정: 합성→검증 → 검증→합성

항목	변경 전 (버그)	변경 후	영향
검증 대상	합성된 영상	WAN 원본 영상	원본 모션 왜곡 없이 정확한 수치 검증 가능

4-3. BgRemover tolerance 조정: 35 → 50

항목	변경 전	변경 후	영향
배경 제거 범위	diff 49 > 35 → 회색 잔상 남음	diff 49 < 50 → 정상 제거	WAN 생성 회색 배경(RGB 206~217) 완전 제거

4-4. APNG disposal=2 수정

항목	변경 전 (disposal=0)	변경 후 (disposal=2)	영향
브라우저 재생	이전 프레임 잔상 누적 → 회색 박스	각 프레임 후 투명 초기화	APNG 재생 시 잔상 제거

---

5. 프롬프트 전략 향상

5-1. volumetric change 금지

항목	변경 전	변경 후	영향
동작 선택 범위	배 호흡, 목 팽창 포함	spatial movement만 허용	WAN Q3가 생성 불가능한 동작 선택 제거 → no_motion 실패율 감소

5-2. 3단계 WAN 실행 가능성 필터

항목	변경 전	변경 후
동작 선택 기준	"가장 쉬운 동작"	Q1(루프 가능?) → Q2(형태 유지?) → Q3(10~40% 범위?)
선택 결과	미세 동작 반복 선택 → no_motion	WAN이 실제로 생성할 수 있는 동작만 선택

5-3. identity motion 우선 원칙

항목	변경 전	변경 후	영향
동작 선택 방향	LOWEST DIFFICULTY	MOST NATURAL motion	"안전한 동작"이 아니라 "특징적인 동작"을 우선 시도

5-4. Negative 우선 원칙

항목	변경 전	변경 후
조정 전략	positive 강화 위주	negative 차단 위주 (PRIMARY)
WAN 반응성	positive 유도에 약한 반응	negative 차단에 강한 반응

5-5. 프롬프트 누적 방지

항목	변경 전	변경 후	영향
positive 길이	무한 누적 → 300자+	150자 초과 시 리셋	서로 충돌하는 지시 방지
negative 길이	무한 누적	200자 초과 시 리셋	positive 표현이 negative에 복사되어 동작 억제되는 최악 사례 방지
STEP G	없음	positive 표현 → negative 복사 절대 금지	동작 자체가 억제되는 문제 근본 차단

5-6. 연속 실패 시 액션 전환

항목	변경 전	변경 후	영향
동일 액션 실패	같은 동작으로 계속 재시도	3회 연속 실패 → analyze_with_exclusion()	구조적으로 불가능한 동작에 시도 횟수 낭비 방지

5-7. 하드코딩 분류 제거

항목	변경 전	변경 후	영향
동작 결정	fish/bird/frog 별 분기 코드	Gemini 자유 판단	미지 이미지에도 대응 가능한 범용 파이프라인

---

6. 종합 — 파이프라인 성숙도 변화

단계	시점	상태
초기	03-06 초반	영어 프롬프트, 6000자, 정지 영상 반복, 수치 버그
중기	03-06 후반	중국어 전환(PSNR +2.6dB), /255 버그 수정, 물고기 첫 통과
안정기	03-07	pingpong, 마스킹 후처리, AI Validator mp4 직접 피드, 물고기 APNG 완성
범용화	03-08	수치 검증 대규모 오탐 수정, ghosting 감지 강화, 하드코딩 제거
현재	03-09	60개 테스트 이미지, 코끼리/헬리콥터 등 다양한 이미지 테스트 진행 중

핵심 수치 요약

지표	초기 → 현재
PSNR	30.0 dB → 32.6 dB
생성 시간	steps 30 → 20 (33% 단축)
검증 항목	7개 → 8개 (+ghosting)
프롬프트 크기	6000자 → 2450자
분류 분기	fish/bird/frog 3종 → 없음 (범용)
AI 입력	프레임 3장 → mp4 직접 전달
마스킹	없음 → 후처리 합성 (고정 부위 원천 보호)
배경 제거 tolerance	35 → 50
성공 루프	첫 성공 즉시 return → 전체 시도 후 선택