poster:홍보 이미지 / 포스터
경계 (먼저 이 섹션을 읽으세요)
| 요구 사항 | 사용할 것 |
|---|
| 단일 데이터 차트(막대/선/원형/흐름/타임라인) | diagram을 사용하세요. 이 스킬을 사용하지 마세요. |
| 단일 시각 자료: 포스터/장문 이미지/커버/배너/카드/전시판 | 이 스킬 |
| 여러 페이지 프레젠테이션 | make-ppt |
| 수식이 포함된 문서 | md2docx |
로컬 시스템의 한계: 확산 모델 가중치나 로컬 추론 능력이 없으며, 사진이나 사실적인 삽화를 생성할 수 없습니다.
이 스킬은 기하학/벡터 스타일만 가능합니다(정밀하게 만들 수는 있지만, 세밀한 사실적 묘사는 불가능).
불변의 규칙
- 점 목록을 수동으로 작성하지 마십시오. 도형은 항상
engine.geometry의 파라메트릭 원시 요소(circle/leaf/cloud/wave/heart…)를 사용하세요.
이들은 내부적으로 적응형 세분화를 수행합니다. 수동 좌표는 '눈에 띄는 폴리곤 근사'의 원인입니다.
- 텍스트도 Path를 따르세요. 별도의 텍스트 그리기 방식을 사용하지 마십시오.
engine.typography가 줄 바꿈/세로 쓰기/금칙 문자 처리를 담당합니다.
- 코드를 수정한 후에는 먼저 모듈 캐시를 지우세요.
python 도구의 인터프리터는 요청 간에 공유됩니다:
for m in [k for k in sys.modules if k.startswith("engine")]: del sys.modules[m]
- 1-2px 수준의 결함을 확인하기 위해 이미지 미리보기에 의존하지 마십시오.
read_image 미리보기는 크기가 조정되어 가짜 간격이 발생할 수 있습니다.
engine.check.check_canvas()의 어설션을 사용하거나 픽셀 수준 통계를 수행하세요.
- 성능: 대규모 픽셀 작업은 C 레이어에 맡기고, 먼저 프로파일링한 후에 수정하세요.
- 단색(검정/흰색/회색) 반투명 오버레이는 3채널 매핑이 동일하므로, 256개 항목 LUT +
bytes.translate를 사용하세요.
실제 측정 결과 픽셀 혼합 루프가 71%(6.6초)를 차지했으며, 수정 후 0.05초로 동일한 수학적 결과를 얻었습니다.
- 전체 행의 단색 채우기는 슬라이스 할당을 사용하고, 픽셀당 3바이트를 개별적으로 쓰지 마세요.
- zlib 레벨 6을 사용하세요. 레벨 9보다 두 배 빠르며 파일 크기는 15%만 더 큽니다.
- 작업을 시작하기 전에
cProfile을 사용하세요: 이 프로젝트의 가장 큰 병목은 기하학 알고리즘이 아닌 알파 혼합입니다.
세 가지 접근 모드
| 모드 | 입력 | 적용 사례 |
|---|
| A 템플릿 | templates/*/을 복사하고 content.json만 수정 | 일반 홍보 이미지 (80% 시나리오) |
| B 조립 | layout.json (스켈레톤 + 블록 목록 + 매개변수) 작성 | 구조 변경 필요, 요소가 표준적일 때 |
| C 자체 그리기 | engine.canvas.Canvas로 직접 그리기 | 참조 이미지 모방, 독특한 레이아웃 |
디렉토리 구조
engine/
canvas.py 디스플레이 리스트 (Canvas.fill/stroke/clip, 레이어 static/dynamic)
path.py Path (M/L/C/Q/Z) + 적응형 세분화
geometry.py 23개 파라메트릭 원시 요소
fonts.py 글꼴 레지스트리 + 글리프→Path + 결자 탐지
typography.py 줄 바꿈/금칙 문자/구두점 압착/세로 쓰기/자간
theme.py 테마 (6개 스킨 + 스타일 매개변수) + 9개 캔버스 프리셋
blocks.py 21개 선언형 블록
layouts.py 9개 스켈레톤 (좌우 분할 포함)
render.py 조립 + CLI
check.py 경계/대비/글자 크기/색상 수/결자/슬롯 어설션
cache.py 정적 레이어 비트맵 캐시 (기본 비활성화, 실제 측정은 refs/workflow.md 참조)
backends/ raster.py (PNG), pdf.py (벡터 PDF), svg.py
packs/ 소재 팩 (guofeng 중국풍, tea 다기), 필요 시 로드
templates/ 완성된 레시피 (content + layout)
실행 전제 조건
- 의존성 설치:
pip install -r requirements.txt (단 하나의 의존성: fontTools)
- 글꼴: 이 저장소는 글꼴 파일을 포함하지 않습니다. 엔진은 시스템에 설치된 글꼴을 읽습니다 — 기본적으로
/system/fonts, /usr/share/fonts, ~/.fonts 등의 일반적인 디렉토리를 스캔합니다. 글꼴이 다른 곳에 있으면 환경 변수
POSTER_FONT_DIR을 사용하여 글꼴 디렉토리를 가리키세요.
- 인터넷 연결 불필요, Office/GUI 불필요: 래스터화, PDF, SVG 세 가지 백엔드는 모두 순수 Python으로 구현되었습니다.
빠른 시작
python -m engine.render templates/minimal-poster/layout.json -o out.png
python -m engine.render templates/minimal-poster/layout.json -o out.pdf \
--preset a4-portrait --for print
python -m engine.render ... --theme guofeng --preset xhs-3x4
python -m engine.render --list
Python에서 호출:
from engine.render import render, load_json
render(layout, content, theme="minimal", preset_name="xhs-3x4",
out="out.png", for_="publish")
외부에 노출된 네 개의 노브
| 노브 | 값 | 설명 |
|---|
preset | xhs-3x4 / sq-1x1 / story-9x16 / wechat-cover / video-16x9 / info-long / a4-portrait / a3-portrait / rollup-85x200 | 크기 및 안전 영역 |
--for | draft / preview / publish / print | 선명도 및 출력 (refs/workflow.md 참조) |
--format | png / pdf / svg | 기본값: print→pdf, 나머지는 png |
--deco | 0/1/2 (테마 내) | 장식 밀도; 미관과 파일 크기에만 영향, 속도에는 거의 영향 없음 |
quality 매개변수는 없습니다: 품질 하한은 원시 요소의 적응형 세분화 + 서브픽셀 커버리지 + check.py에 의해 보장됩니다.
제한 사항 (사실대로 알림)
- 사진, 사실적인 삽화, 3D를 제작하지 않습니다. 반사실적인 도구는 가능하지만(각각 약 100–200줄, 6개 레이어), 인물은 권장하지 않습니다.
- PDF 첫 번째 버전은 텍스트가 경로로 변환됩니다: 시각적으로는 정확하지만 선택 및 검색이 불가능합니다.
- PDF는 RGB만 지원하며 CMYK나 별색을 지원하지 않습니다. 인쇄 전에 별도로 변환해야 합니다.
- 큰 제목/가는 선은 ss=2일 때
--for publish (ss=3)를 사용하는 것이 좋습니다.
- 희귀 문자에 대해 글리프가 누락될 수 있습니다.
check.py는 누락된 문자를 보고하며, POSTER_FONT_DIR을 통해 글꼴을 지정할 수 있습니다.
- 첫 번째 렌더링은 약 6초 추가 소요 (글꼴 파일 구문 분석). 동일 프로세스 내 후속 렌더링은 재사용됩니다. 반복 작업 시 프로세스를 자주 재시작하기보다 연속적으로 호출해야 합니다.
- 웜 상태 소요 시간 참고: preview ≈1.6초, publish ≈2.7초 (1080×1440의 3240×4320 출력 기준).
- 세로 쓰기 구두점은 이동만 하고 회전하지 않습니다. 숫자/영문 세로 쓰기도 회전하지 않습니다. 여러 글꼴 간 적응은 구현되지 않았습니다.
주의 사항 (겪었던 함정)
성능
- 반투명 오버레이: 모든 색상에 대해 채널별 LUT를 사용합니다 (실제 측정 13초→2.5초). 새로운 '대규모 픽셀 단위' 기능을 추가하기 전에 먼저 테이블 조회가 가능한지 생각하세요.
- 대형 PNG 디코딩: 5760×3240 완전 디코딩 10초+. 배경 소재는 1500px 이하를 권장하거나, JPEG (DC 계수만 디코딩하여 한 자릿수 더 빠름)를 사용하세요.
- print 모드는 강제로 ss=1: A4@ss3 실제 측정 52초.
- 정적 레이어 캐싱은 실제로 비용 효율적이지 않습니다 (40MB 비트맵 IO ≈ 렌더링 비용).
--cache는 기본적으로 비활성화되어 있습니다.
글꼴
- 모든 FZ 글꼴은
∂ ħ ∇ 및 위 첨자 숫자 ⁻³⁵가 누락되어 있습니다. 누락된 문자는 자동으로 건너뛰며 오류를 보고하지 않습니다 (수식이 ψ/ t = i Hψ가 될 수 있음).
- 수식/단위를 작성하기 전에 먼저
fonts.missing(text, family)를 확인하세요. 실제 사용 가능한 기호는 ψ ∫ ≈ ∝ λ ∞ → · 정도입니다.
레이아웃
hero 여러 줄은 영역 높이가 줄 수 × 줄 높이보다 크거나 같아야 합니다. 그렇지 않으면 다음 블록으로 밀려납니다.
banner / card-grid / cover의 비율은 경험적입니다. 내용을 변경하면 미세 조정이 필요할 수 있습니다.
- 와이드스크린에서 CTA는 반드시
max_width를 설정해야 합니다. 그렇지 않으면 진행률 표시줄처럼 전체 행을 차지합니다.
- 배경 이미지에 포함된 텍스트는 전경과 충돌합니다. 텍스트가 없는 소재 (사진/텍스처/일러스트)를 선택하세요.
이미지 소재
- JPEG의 PNG 출력은 DC 버전입니다 (8x 축소판, 픽셀화됨). 선명함을 원하면 PDF를 출력하거나 PNG 소재를 사용하세요.
- PDF에 JPEG를 직접 포함하면 재인코딩 없이 최고 품질을 유지합니다.
- 확장자가 없는 소재도 인식 가능합니다 (파일 시그니처로 판단).
엔지니어링 습관
python 도구의 모듈 캐시는 요청 간에 공유됩니다. 각 테스트 시작 시 sys.modules에서 engine* / packs*를 지우세요.
- 개발 디렉토리와 설치 디렉토리를 분리하고, 수정 후
copytree로 동기화하세요 (__pycache__ 무시).
scene의 objects_pack 가져오기 실패는 자동으로 단순 버전으로 대체되며 오류를 보고하지 않습니다.
상세 문서 (필요 시 읽기)
| 파일 | 내용 |
|---|
refs/workflow.md | 참조 이미지 해부 → 회색조 모형 → 채색 → 텍스트 추가 → 검수; 선명도 수준 및 성능 벤치마크 |
refs/canvas-api.md | Canvas / Path / geometry 빠른 참조, 누락된 기능에 대한 대체 방법 |
refs/presets.md | 모든 크기, 안전 영역, 인쇄 도련 및 pt 환산 |
refs/packs.md | 소재 팩 프로토콜 및 '요구 사항별 패키징' 수집 워크플로우 |
refs/styles.md | 스타일 매개변수, 6개 내장 스타일 핑거프린트, theme_overrides, 스타일 모방 워크플로우 |
refs/analyze.md | 참조 이미지 분석: 색상 추출/명암/레이아웃 중심/밀도 → 테마 초안 |