Visual Asset Pipeline

Visual Asset Pipeline은 프롬프트, 여러 에셋이 들어 있는 이미지 시트, 웹페이지 캡처, 스케치, 이미지 폴더를 바로 쓸 수 있는 프로덕션 에셋 패키지로 변환하는 파이프라인입니다.

한국어 | English | 日本語 | 简体中文 | Español

기본 진입점은 한국어입니다. English 문서는 위 링크에서 열 수 있습니다.

현재 상태: alpha. 로컬 CV 기반 파이프라인은 동작하며, segmentation, semantic naming, OCR, SVG 변환은 교체 가능한 어댑터로 확장하도록 설계되어 있습니다.

지원 범위

아이콘만을 위한 도구가 아닙니다. 아이콘은 여러 profile 중 하나입니다.

• 아이콘, 심볼 팩
• 캐릭터 시트, 포즈 보드
• 스프라이트 시트, 게임 오브젝트
• 웹페이지/랜딩페이지 시각 에셋
• UI 배지, 버튼, 상태 variant, 앱 에셋
• 스티커, 이모트, 투명 컷아웃

차별점

• 완벽한 grid만 전제로 하지 않고, 지저분한 시각 입력에서도 foreground component를 기준으로 탐지합니다.
• PNG, WebP, 선택 SVG, sprite sheet, metadata, validation report, contact sheet, crop preview, ZIP까지 실제 downstream 사용에 맞게 패키징합니다.
• anti-aliasing, 그림자, outline, glow, optical centering 같은 품질 요소를 보존하도록 설계했습니다.
• 파일명 생성, 검증, 중복 감지, 스타일 일관성 점검을 후처리 잡일이 아니라 파이프라인 일부로 다룹니다.
• Codex skill, Python CLI, npm global CLI, npx one-off 실행을 모두 지원합니다.

파이프라인

더 쉬운 설명은 Visual Asset Pipeline 프로세스 설명에 정리했습니다.

1. 입력 분석: 레이아웃, 배경, 텍스트, 간격, grid 힌트, 예상 개수.
2. 시각적 위치 탐지: 동일 grid만 믿지 않고 foreground component를 찾습니다.
3. 분리/배경 제거: anti-aliasing, 그림자, outline, glow를 최대한 보존합니다.
4. 정리: 캡션, 라벨, 숫자, 가이드라인, 작은 노이즈를 제거합니다.
5. 정규화: profile별 padding, optical center, 요청 size를 적용합니다.
6. 검증: 잘림, blur, duplicate, 텍스트 잔여물, 배경 artifact, 스타일 편차를 감지합니다.
7. 패키징: PNG, WebP, 선택 SVG, sprite sheet, metadata, validation report, contact sheet, ZIP을 만듭니다.

설치

Python

git clone https://github.com/Jun0zo/visual-asset-pipeline.git
cd visual-asset-pipeline
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install -e ".[dev]"

확인:

visual-asset-pipeline --help
pytest

짧은 alias도 제공합니다.

vap --help

npm / npx

npm 패키지는 Python 파이프라인을 실행하는 작은 Node.js CLI wrapper를 제공합니다. 설치 시 가능하면 패키지 내부 .venv를 만들고 Python dependency를 설치합니다.

npm install -g github:Jun0zo/visual-asset-pipeline
vap --help

한 번만 실행하려면:

npx --yes github:Jun0zo/visual-asset-pipeline --help

Python 환경을 직접 관리하고 싶다면 VAP_SKIP_PYTHON_INSTALL=1을 설정한 뒤 npm install을 실행하면 됩니다.

빠른 사용 예시

프롬프트에서 생성 brief 만들기:

visual-asset-pipeline brief \
  --prompt "Create 48 forest exploration icons in watercolor style." \
  --profile icon \
  --output work/forest-assets

생성된 이미지 시트에서 에셋 추출:

visual-asset-pipeline extract \
  --input work/forest-assets/generated-sheet.png \
  --output work/forest-assets/export \
  --prompt "Create 48 forest exploration icons in watercolor style." \
  --profile icon \
  --expected-count 48 \
  --sizes 128,256,512,1024

이미 분리된 이미지 폴더 정규화:

visual-asset-pipeline normalize \
  --input work/raw-assets \
  --output work/normalized-assets \
  --profile web \
  --sizes 256,512

출력물

• png/<size>/*.png
• webp/<size>/*.webp
• svg/*.svg optional
• sprites/sprite_<size>.png
• sprites/sprite_<size>.json
• metadata.json
• validation_report.json
• contact_sheet.png
• crop_preview.png
• visual_asset_package.zip

이 결과물은 Figma, React, Flutter, iOS, Android, 웹 앱, Unity, Godot 같은 환경에서 바로 쓸 수 있도록 설계되어 있습니다.

Crop Preview Overlay

추출을 실행하면 export 폴더에 crop_preview.png도 함께 생성됩니다. 빨간 박스는 padding이 적용된 최종 crop 영역이고, 옅은 흰 박스는 원래 detection 영역입니다. 번호는 metadata와 연결되므로 어떤 에셋이 어떻게 잘릴지 바로 확인할 수 있습니다.

Codex Skill 설치

Skill은 skill/visual-asset-pipeline에 포함되어 있습니다.

cp -R skill/visual-asset-pipeline "${CODEX_HOME:-$HOME/.codex}/skills/"

Codex에서 이렇게 사용할 수 있습니다.

Use $visual-asset-pipeline to extract this character sheet into transparent PNG, WebP, sprite sheet, ZIP, and metadata.

Profile

| Profile | 용도 | | --- | --- | | icon | 아이콘, 심볼, 배지 | | character | 캐릭터 포즈, 마스코트, 아바타 | | sprite | 게임 프레임, prop, effect | | web | 랜딩페이지 이미지, 로고, 일러스트 | | ui | 버튼, 배지, 상태 variant | | sticker | 스티커, 이모트, outline/glow cutout | | auto | 혼합 또는 알 수 없는 시트 |

개발

python3 -m pip install -e ".[dev]"
pytest
npm pack --dry-run

구조

src/visual_asset_pipeline/
├── analysis.py        # 입력 분석과 레이아웃 메타데이터
├── detection.py       # 시각적 에셋 위치 탐지
├── segmentation.py    # foreground mask와 배경 제거
├── cleanup.py         # 캡션, 가이드, 아티팩트, 노이즈 정리
├── normalization.py   # optical centering과 profile 기반 export
├── validation.py      # 품질 검사, 중복, 스타일 검사
├── naming.py          # 의미 있는 파일명 생성
├── packaging.py       # 이미지 export, 메타데이터, 리포트, ZIP
└── cli.py             # 명령행 인터페이스

자세한 내용은:

• Architecture
• Library recommendations
• Name candidates

선택적 확장

기본 파이프라인은 Pillow, NumPy, scikit-image로 로컬에서 동작합니다. 프로덕션에서는 아래를 교체하거나 추가할 수 있습니다.

• SAM, RMBG, rembg를 segmentation에 사용
• CLIP, SigLIP, DINOv2, 멀티모달 LLM으로 semantic naming과 duplicate detection 개선
• OCR로 캡션과 라벨 제거 강화
• vtracer, potrace, Illustrator, 호스팅 vectorization 서비스로 SVG 출력
• Figma, React, Flutter, iOS, Android, Unity, Godot, TexturePacker용 코드 생성

로드맵

• pivots, hitbox, 9-slice, state group, animation group 같은 profile 전용 metadata
• 모델 기반 extraction adapter
• true vector export pipeline
• 멀티모달 semantic naming 검토 UI
• Figma plugin export
• 프레임워크와 게임 엔진용 codegen
• 실제 에셋 시트로 만드는 visual regression benchmark suite