1. 얼굴장면과 의상에서 분리된 인물 정체성 기준
TheROAD · Reality-Oriented AI Direction · implementation atlas
시나리오 PDF에서 최종 이미지, 웹북, HTML까지
TheROAD의 현재 구현을 입력 데이터, 구조화 판단, 시각 캐논, 공간 도면, 가이드 이미지, 최종 샷, 계보 저장, 출판 출력 순으로 추적한 기술 문서입니다. 각 다이어그램은 흐름만 짧게 보여주고, 실제 계약은 바로 아래 표에서 설명합니다.
30분석된 씬
58선택·생성된 최종 샷
55인물·장소·소품·아웃룩 캐논
167완주 프로젝트 이미지 자산
59완료된 실행 단계
i
수치는 2026.07.11 완주 프로젝트
8ad94c03… / 에피소드 e666c62b…의 읽기 전용 DB 스냅샷입니다. 웹북·PDF·HTML은 현재 코드 경로를 설명하며, 이 샘플 프로젝트에서는 별도 출판 실행을 하지 않았습니다.01 / MAP
전체 제작 지도
하나의 거대한 프롬프트가 아니라, 서로 다른 책임을 가진 구조화 단계가 결과를 다음 단계의 증거로 넘깁니다.
기획안·시나리오PDF, 프로젝트 설정
텍스트 정규화전문·씬·요약·세계관
스토리 구조Beat, Shot, VE, 의존성
시각 캐논인물·의상·소품·상태
공간 설계도면·배경·카메라
가이드 체인블로킹·스케치·연속성
최종 이미지참조 조립·검수·계보
출판 출력웹북·PDF·HTML ZIP
| 구간 | 핵심 입력 | 핵심 판단 | 대표 출력 | 다음 단계가 믿는 SOT |
|---|---|---|---|---|
| 1. 수집 | 기획 PDF, 에피소드 PDF | 문서 종류, 프로젝트·에피소드 연결, 제작자 정정 | 원문 전문과 기획 컨텍스트 | Episode.fulltext, PlanningContext |
| 2. 분석 | 정리된 전문 | 씬 경계, 사건, 세계 규칙, beat와 shot 분해 | 씬·샷 구조 JSON | 체크포인트 manifest + scene_still |
| 3. 캐논 | 씬·샷 전문 | 동일 인물·장소·소품 병합, 관계·상태·아웃룩 분리 | C##, L##, P##, O## | entity_canon, character_outlook |
| 4. 공간 | 장소, shot staging | 실내외 분류, 도면 위상, plate 순서, 카메라 가시물 | FP, background plate, projection card | 구조 readback + image_asset |
| 5. 참조 | 캐논과 공간 자산 | 어떤 이미지가 정체성·의상·배경·구도 SOT인지 분리 | face, outlook, composite, guide | pipeline_role + input_image_ids |
| 6. 합성 | 샷 프롬프트 + 실제 참조 | 참조 역할 지시, 이미지 생성, 계약 검수와 재시도 | scene_still 이미지 | primary asset + actual_attached_refs |
| 7. 출판 | 원문, 캐논, 스틸 | 웹 에피소드 재구성, 문단-이미지 배치, 포맷 변환 | 웹북 JSON, PDF, HTML ZIP | WebbookPackage, assets/exports |
핵심 설계
이미지 모델은 마지막 렌더러입니다. TheROAD의 주된 일은 그 전에 “무엇이 같은 것인지, 어디에 있어야 하는지, 어떤 이미지가 어떤 사실을 책임지는지”를 구조화하고, 렌더 뒤에도 실제 첨부 UUID를 계보로 남기는 것입니다.
02 / TEXT
입력과 텍스트 분석
원문을 축약해 버리는 대신 전문을 보존하고, 서로 다른 구조화 작업이 단계별 체크포인트를 만듭니다.
PDF 업로드기획안 / 에피소드
정리·분할텍스트 / 씬
Beat·Shot행동 단위 / 카메라 단위
Entity인물 / 장소 / 소품
DirectorVE / staging / flow
상세 T2I검수 가능한 샷 계약
| 묶음 | 주요 단계 | 무엇을 결정하는가 | 출력·소비자 | 안전장치 |
|---|---|---|---|---|
| 문서 기반 | planning_doc_analysis, text_cleanup | 기획 의도와 에피소드 원문을 분리 보존하고, 후속 프롬프트에 필요한 기획 섹션을 선택 주입합니다. | PlanningContext, 정리된 fulltext | PDF 전용 모델 경로, 전문 보존 |
| 서사 골격 | scene_segmentation, episode_summary, visual_world_rules, scene_save | 씬 경계, 에피소드 전반의 사건·시대·지역·시각 톤을 구조화합니다. | 씬 전문, 요약, 세계 규칙 | 원문 사실과 전역 스타일의 역할 분리 |
| 촬영 단위 | beat_extract, shot_extract, shot_validator | 사건을 beat로 나누고, 실제 생성 가능한 shot으로 세분한 뒤 스키마·근거·중복을 검증합니다. | shot manifest | 검증 실패 시 재시도·부분 중단 |
| 요소 캐논 | entity_all_*, entity_extract_*, merge, relation, filter, detail | 이름이 다른 동일 대상, 상태 변형, 시각적 관계를 정규화해 재사용 가능한 캐논을 만듭니다. | entity_canon, 관계 checkpoint | 구조 ID로 조인, 저빈도 스킵 기록 |
| 감독 판단 | shot_selection, scene_director, shot_director | 생성할 샷과 실제 프레임 안에 존재해야 할 VE(Visible Entities)를 결정합니다. | 선택 샷, VE | 선택 샷만 후속 이미지 비용 사용 |
| 촬영 설계 | scene_camera_flow, shot_dependency, shot_staging, scene_consistency | 씬 내 카메라 흐름, 샷 간 의존, 자세·깊이·프레이밍, 연속성 조건을 구조화합니다. | staging, dependency, continuity | 구조 필드 중심, 자유문자 파싱 금지 |
| 생성 계약 | scene_detail, shot_dependency_t2i, t2i_review | 참조 토큰, 카메라, 행동, 배경, 소품 소유권을 최종 생성 프롬프트로 조립하고 검수합니다. | t2i_variations_json | 참조 계약 위반 시 scene 생성 차단 |
실제 한 샷의 구조화 예
씬 1 · 샷 1
Shot description
한쪽 신발이 벗겨진 한국인 남자가 우거진 수풀 사이를 달리며 한 발을 허공에 내딛고 있는 도중의 전신 구도
Visible entities
C06 한국인 남자, L01 우거진 숲속 및 사건 현장
Outlook binding
C06O06으로 인물과 해당 장면 의상을 결합
생성 계약으로 확장
동작
mid-stride, 한쪽 맨발, 재킷이 진행 반대 방향으로 펄럭임
카메라
후방 3/4 관찰 시점, 전신이 읽히는 추적 구도
참조 종류
character reference + outdoor composition guide
사실과 연출
원문·직접 추출 설명·제작자 정정은 세계 사실의 근거입니다. 카메라 각도와 프레이밍은 연출 재량이지만, 원문에 없는 날씨·재질·표면 상태를 전역 톤에서 사실처럼 증식하지 않도록 프롬프트 팩이 분리되어 있습니다.
03 / CANON
인물·의상·상태를 분해한 시각 캐논
인물 한 장을 매번 다시 만드는 대신 얼굴 정체성, 착장, 합성 전신, 이야기 상태를 독립 자산으로 관리합니다.
얼굴 캐논identity SOT
아웃룩의상·착용 상태
합성 전신얼굴 + 의상
상태 변형부상·기절·사망 등
2. 아웃룩마네킹형 착장으로 핏·레이어·크기 관계 확인
3. 합성샷 생성에 직접 붙이는 character composite
4. 상태같은 얼굴·착장을 유지한 별도 시각 상태
| 자산 | 입력 | 책임 | 대표 role | 계보 |
|---|---|---|---|---|
| Face reference | character canon + entity_t2i | 얼굴, 연령, 기본 외형의 장기 정체성 | reference_face | 루트 자산 |
| Outlook reference | outlook_phase1~3 | 옷의 종류뿐 아니라 실제 착용 방식, 레이어, 신발·장신구 관계 | reference_outlook | 루트 자산 |
| Composite | face + outlook | 해당 장면에서 바로 사용할 전신 passport | reference_composite | input_image_ids=[face, outlook] |
| State variant | composite/face + staging state | 부상·노화·기절·사망 등 순간 상태를 평상시 캐논과 분리 | character_state_variant | 원 캐릭터 reference UUID |
| Prop reference | prop canon + entity_t2i | 소품 자체 형태와 크기를 고정하고, 장면에서 어떻게 들고·입고·사용할지 참조 역할로 연결 | reference_prop 계열 | 샷의 actual_attached_refs |
분해의 이유
얼굴, 의상, 상태를 한 프롬프트에 섞으면 한 요소를 바꿀 때 다른 요소도 흔들립니다. 자산을 분해하면 “같은 사람의 다른 옷”, “같은 옷의 다른 상태”, “상태 변형 뒤에도 같은 정체성”을 UUID 계보로 확인할 수 있습니다.
04 / SPACE
가장 어려운 배경을 도면과 plate 체인으로 분해
배경은 텍스트 한 줄로 생성하지 않습니다. 장소 그룹, 평면 위상, 카메라 가시물, 렌더 순서, 앞서 만든 배경 참조를 따로 결정합니다.
장소 분류실내·실외·그룹
마스터 플랜필요 배경 카탈로그
Floor Plan방·문·가구 위상
Readback기하·마커 검증
Render Planplate·anchor·DAG
Background연속 참조 렌더
1. 도면 SOT방, 문, 창, 가구, 옥상 연결을 번호로 고정
2. 배경 plate도면 위상을 실사 공간으로 투영
3. 최종 샷배경은 위치 SOT, 캐릭터 reference는 정체성 SOT
| 단계 | 구조 입력 | 산출 계약 | 실패·검증 |
|---|---|---|---|
| background_classify | 선택 샷, location canon, VE | 실내외 판정, building group, shot-location 연결 | 구조 ID 조인, 텍스트 이름 파싱 금지 |
| background_master_plan | 장소 그룹 + 씬 전문 | 필요한 배경 ID, 용도, 의존 관계와 카탈로그 | 카탈로그 hash로 하류 stale 판정 |
| floor_plan_prompt/render | 장소 사실 + scale guideline | 도면 프롬프트와 실제 FP 이미지 | 프롬프트 버전·컨텍스트 hash |
| geometry/semantic readback | FP 이미지 + 마커 계약 | 문·경계·구역·마커 의미를 구조 데이터로 되읽음 | VLM 판정, 기하 오류는 후속 gate |
| projection / partition | shot staging + readback | 카메라에서 실제 보이는 요소, plate 묶음, anchor와 ref DAG | 샷별 projection SOT |
| background_prompt/render | 도면, 이전 plate, 배경 프롬프트 | 실제 background_render 이미지와 이전 배경 lineage | 파일 존재, status ok, UUID resolve |
실내 기본 경로
FP가 위상 SOT입니다. 도면 readback과 projection card가 카메라에 보이는 범위를 정하고, background plate가 그 구조를 실사화합니다.
야외 선택 경로
기본 site-layout 체인과 opt-in direct-canon 체인이 공존합니다. 기능 플래그가 applicability와 config hash를 바꾸며, 비활성 경로는 현재 실행에서 빠집니다.
05 / GUIDE
복잡 구도는 먼저 배치하고, 나중에 실사화
공간과 인물의 동작이 복잡할수록 모델에게 완성 이미지를 한 번에 맡기지 않습니다. 도면, 블로킹, 마네킹 스케치가 각각 다른 문제를 먼저 해결합니다.
야외: 항공 배치 → 카메라 블로킹 → 포즈 스케치 → 실사
1. Aerial base도로·해안·수풀의 상대 위치
2. Blocking카메라 위치, 시야각, 인물 슬롯
3. Camera sketch실제 프레이밍과 몸 동작을 선화로 검증
4. Final still인물 passport와 장면 사실을 적용
| 단계 | 이 단계가 책임지는 것 | 책임지지 않는 것 | 다음 입력 |
|---|---|---|---|
| Aerial base | 장소 topology, zone, 접근 경로 | 최종 카메라, 인물 얼굴, 영화 조명 | blocking의 공간 base |
| Shot blocking | 카메라 점, 시야 방향, 인물 슬롯 | 의상·정체성·실사 재질 | camera sketch의 control |
| Camera sketch | 포즈, 접촉점, 프레이밍, 깊이 | 얼굴·의상·최종 질감 | scene_image의 composition guide |
| Final still | 모든 역할이 분리된 참조를 조합해 실사 결과 생성 | 가이드의 마커·선화 스타일 복제 | 검수·primary 저장·출판 |
실내 고정 자세: 배경 underlay → 등록 포즈 → 최종 샷
1. Underlay방 구조와 사고 흔적을 먼저 고정
2. Registered guide접촉점, 손, 몸의 기울기, 소품 위치 잠금
3. Final still상태 캐논과 포즈 가이드가 함께 첨부
Fail closed
가이드가 없거나 구조키가 모호하면 잘못된 가이드를 억지로 붙이지 않습니다. 정확한 group·background·guide hash를 우선 해석하고, 모호한 pair는 unresolved 진단으로 남기는 쪽이 “틀린 참조”보다 안전합니다.
06 / SHOT
최종 샷은 참조 역할을 조립한 결과
최종 프롬프트와 이미지 목록은 같은 데이터가 아닙니다. 어떤 이미지가 실제로 첨부되었는지 UUID와 역할 메타데이터로 별도 보존합니다.
선택 샷scene_still
참조 해석캐릭터·소품·배경
가이드 해석pose·composition·prev
이미지 생성role별 지시문
Readback계약·단일 프레임
Primary 저장계보·감사 링크
| 참조 역할 | 예시 자산 | 생성 모델에 전달하는 책임 | 영속화 |
|---|---|---|---|
| background_render | chain_bg / plate | 공간 구조·재질·가시 배경. 캐릭터 정체성이나 새 포즈의 SOT가 아님 | actual_attached_refs + input_image_ids |
| character reference | face / composite / state | 인물 정체성, 해당 장면 의상, 상태 변형 | asset_id + pipeline_role |
| prop reference | 소품 passport | 실물 형태와 상대 크기. 사용 동작은 본문·pose guide가 결정 | asset_id + label |
| composition guide | outdoor_camera_sketch | 프레이밍·깊이·인물 배치·포즈. 선화 스타일과 마커는 복제 금지 | guide UUID → scene UUID edge |
| registered pose | indoor_pose_guide | 접촉점, 자세, 손·소품 위치 | 구조키 post-hoc resolve 포함 |
| previous frame | 이전 primary still bytes | 겹치는 장소의 안정된 세부와 연속성. 현재 샷의 카메라·시간은 본문 SOT | source_still_id → primary image UUID |
생성 전 gate
- 선택 샷에 필요한 캐릭터·아웃룩 참조가 준비되었는지 확인
- required reference contract가 충족되지 않으면 이미지 호출 차단
- 가이드·배경 결측은 정책별로 fail-closed 또는 명시적 fallback
- 이미지 호출 예산 cap과 resume 상태 확인
생성 후 gate
- scene review와 단일 연속 프레임 readback
- 거부본은 보존하되 primary로 선택하지 않음
- 실제 첨부 UUID, generation_call_id, unresolved 목록 기록
- 선택 스틸 수와 primary scene asset 파일 수를 완료 검증
중요 구분
reference_image_ids는 기존 장면 계보 용도로 유지되고, 실제 I2I 첨부 자산은 input_image_ids와 actual_attached_refs에 기록됩니다. 이 구분이 캔버스 엣지와 샷 모달 생성 트리의 근거입니다.
현재 생성되는 이미지 자산 전체 범주
| 범주 | 대표 asset / pipeline role | 생성 목적 | 조건 |
|---|---|---|---|
| 도면 | floor_plan, floor_plan light sidecar | 장소의 방·문·창·가구·동선을 2D 위상으로 고정하고, 하류가 읽기 쉬운 단순화 변형을 제공합니다. | background mode |
| 장소 기준 | location_aerial, outdoor_canon_photo, outdoor_canon_map | 야외 장소의 광역 구조 또는 장소 passport를 고정합니다. | 기능 플래그별 선택 경로 |
| 배경 | background_render, space_set_bg | 도면·이전 plate·장소 기준을 실제 카메라 배경과 공간 세트로 실사화합니다. | background mode |
| 인물·소품 참조 | reference_face, reference_prop | 정체성과 소품 형태의 루트 passport입니다. | 항상, 저빈도 정책 적용 |
| 착장·합성 | reference_outlook, reference_composite | 착용 방식과 인물+의상 전신을 분리 생성합니다. | outlook 존재 시 |
| 상태 변형 | character_state_variant | 평상시 캐논과 분리된 부상·기절·사망 등 상태 passport입니다. | staging 상태 감지 시 |
| 야외 구도 | outdoor_aerial_base, outdoor_shot_blocking, outdoor_camera_sketch | 장소 배치, 카메라 시야, 마네킹 포즈를 순차적으로 해결합니다. | outdoor site-layout 활성 시 |
| 실내 포즈 | registered_pose_underlay, registered_pose_guide, indoor_pose_guide | 배경 위의 접촉점과 고정 자세를 등록합니다. | 연속성·immobilized·shared pose 정책 |
| 연속성 crop | zoom_continuity_crop | close/insert 계열 후속 샷이 앞 샷의 국소 세부를 유지하도록 합니다. | zoom continuity 활성 시 |
| 최종 | scene_still | 샷 프롬프트와 실제 참조 스택을 조합한 primary·variant·rejected 결과입니다. | 선택 샷 |
07 / RUN
재실행 가능한 실행기와 감사 가능한 저장 구조
단계 실행은 단순 함수 호출이 아니라 applicability, 의존성, 체크포인트, config hash, 원자적 상태 전환, 완료 검증을 포함합니다.
Applicability이번 프로젝트에 필요한가
Dependencies상류 완료·hash 확인
Atomic claimstep_run = running
Executeresume / force / cap
Verify수량·파일·계약
Checkpointmanifest + DB + files
| 계층 | 저장 대상 | 역할 | 대표 키 |
|---|---|---|---|
| PostgreSQL | project_registry, episode | 프로젝트와 에피소드의 영속 ID, 원문, 상태 | project_id, episode_id |
| PostgreSQL | entity_canon, character_outlook | 인물·장소·소품·아웃룩 캐논과 관계 | entity UUID + short_id |
| PostgreSQL | scene_still | 샷 설명, VE, 선택 여부, T2I variations | scene_index + shot_index |
| PostgreSQL | image_asset | 모든 이미지의 role, status, primary, 계보, prompt, 모델 | asset UUID |
| PostgreSQL | step_run | 단계별 상태, 완료 수, 실사용 모델, 시간 | project + episode + step |
| PostgreSQL | llm_call_log | 이미지 호출 감사, 라벨 참조와 생성 입력 | generation_call_id |
| Filesystem | checkpoints/.../manifest.json | 구조화 산출, diagnostics, config hash, resume 근거 | step_id 경로 |
| Filesystem | projects/.../images | reference, floor plan, background, guide, scene 파일 | DB file_path와 연결 |
Resume와 Force의 의미
Resume
완료·파일·hash가 유효한 결과는 재사용하고, 부분 완료 또는 누락된 항목만 이어서 실행합니다. 이미지 호출 cap을 소진한 긴 작업도 같은 경로로 계속할 수 있습니다.
Force
상류 구조나 프롬프트가 바뀐 단계를 다시 계산합니다. 기존 이미지·행을 파괴적으로 덮어쓰기보다 primary를 교체하고 이전 결과는 감사 가능한 상태로 보존하는 경로를 사용합니다.
08 / PUBLISH
이미지 결과를 웹북·PDF·HTML로 출판
생성된 스틸을 단순 폴더로 끝내지 않고, 원문과 구조화 데이터를 다시 조합해 읽을 수 있는 패키지로 내보냅니다.
출판 입력 세트fulltext · entities · primary stills · world guide
웹북 JSON → PDF웹 에피소드 구조화 뒤 long-page 렌더
씬 HTML → ZIP문단·샷·실제 참조 썸네일, JPG 또는 원본 PNG
프로젝트 → JSON전체 구조 데이터 내보내기·가져오기
| 출력 | 입력 | 처리 | 결과 | 검증·선택 규칙 |
|---|---|---|---|---|
| Webbook | Episode.fulltext, EntityCanon, SceneStill, WorldGuide | 시리즈 제목·로그라인·웹 에피소드·섹션·문단·캡션으로 구조화 | WebbookPackage JSON | 웹 에피소드당 최소 분량, 최대 3회 재시도, unknown still 경고 |
| WebbookPackage + scene assets | 샷별 primary 우선, 없으면 최신 original/variant 선택 후 long-page 렌더 | PDF 파일 | vision 기반 PDF validation API | |
| HTML ZIP | 분석된 모든 에피소드 + scene images | 씬 본문, 샷 캡션, 문단 삽입 위치, 실제 첨부 reference 썸네일 조립 | episode HTML + images/ + ZIP | JPG 변환 또는 original PNG 선택 |
| HTML reference | scene asset metadata | actual_attached_refs를 우선 사용하고, 구형 데이터만 VE·T2I ID로 fallback | 배경·합성·소품·상태·가이드 썸네일 | 실제 첨부 SOT 우선 |
| Project JSON | 프로젝트 전체 구조 데이터 | API 내보내기와 가져오기로 프로젝트 이동 | JSON archive | 별도 import endpoint |
현재 경계
이 코드 스냅샷의 자동 출판 끝점은 이미지 기반 웹북·PDF·HTML입니다. 비디오 생성은 아직 현재 manifest의 실행 단계가 아니며, 향후에는 scene_still과 shot dependency를 영상 클립·전환·음향 타임라인의 입력으로 사용하는 확장 지점이 됩니다.
09 / UI
파이프라인 캔버스에서 결과와 계보를 함께 확인
캔버스는 이미지 갤러리가 아니라, 캐논·가이드·배경·최종 샷 사이의 input_image_ids와 구조 엣지를 시각화합니다.
실제 UI 캡처 · 완주 프로젝트 전체 탭클릭하여 확대
| UI 영역 | 보여주는 것 | 근거 데이터 | 사용 목적 |
|---|---|---|---|
| 에피소드 단계 | 분석·이미지 단계의 상태, 모델, 완료 수 | STEP_MANIFEST + step_run | 실행·재실행·진행 모니터링 |
| Entities | 인물·의상·소품·장소, 상태변형, 중간·거부 자산 | entity_canon + image_asset role | 캐논 검수 |
| Image review | 샷별 최종 이미지, reference, 생성 트리 | scene_still + pipeline graph | 결과·입력 이미지 확인 |
| Pipeline canvas | 캐릭터·배경·가이드·샷 노드와 lineage edge | image_asset + input_image_ids + call overlay | 누락·잘못된 참조·dangling 진단 |
| Export studio | 웹북 생성, PDF, HTML ZIP, validation, 다운로드 | WebbookPackage + export files | 출판 산출물 제작 |
10 / APPX
현재 전체 단계 부록
backend/app/core/step_manifest.py의 현재 76개 항목입니다. 기본·조건부·레거시를 함께 표시하며, 검색과 필터는 이 HTML 안에서만 동작합니다.
| 순서 | Step ID | 표시명 | 분류 | 상태 | 적용 조건 | 기본 모델 | 의존 단계 |
|---|