Codex Pet Maker

반려동물 사진 레퍼런스를 2D 도트 캐릭터 마스코트와 GIF/WebP 애니메이션으로 만드는 공개 Codex skill입니다.

A public Codex skill for turning pet photo references into 2D pixel-art mascot concepts and animated GIF/WebP assets.

Current version: 1.0.0

이 repo는 유료 API를 직접 호출하지 않습니다. Codex/agent 환경에서 사용 가능한 이미지 생성 기능으로 프레임을 만들고, 이 repo의 로컬 Python 스크립트로 GIF/WebP 조립, 흔들림 검사, QR 워터마크를 처리합니다.

This repo does not call paid APIs by itself. Bring your own image generation capability from Codex or your agent environment, then use the local Python scripts here to assemble, inspect, and watermark animations.

Public Examples / 공개 예시

아래 우유 GIF는 공개 승인된 생성 마스코트 예시입니다. 원본 사진이 아니며, 도용 방지를 위해 개발자 프로필 QR 워터마크가 0.1 투명도로 전체 픽셀 위에 블렌딩되어 있습니다.

These Uyu GIFs are approved generated mascot examples. They are not original photos. A developer-profile QR watermark is blended over the visible pixels at 0.1 opacity for attribution.

What This Includes / 포함된 것

• pet-to-pixel-mascot: chat-led Codex skill for mascot concepts, expressions, and animation prompts
• assemble_gif.py: local GIF/WebP assembly from finished frame images
• inspect_animation.py: local QA for frame count, size, animation state, and center drift
• watermark_qr.py: optional QR watermarking for approved public branding examples
• examples/synthetic/frames: non-private frames for script testing
• examples/uyu: approved public Uyu GIF examples

This repo intentionally has:

• no hosted backend
• no bundled paid API calls
• no required API key
• no external upload by default
• no committed private pet photos or private generated outputs

이 repo에는 백엔드, 유료 API 호출, 필수 API 키, 외부 업로드, 비공개 반려동물 원본 사진이 포함되지 않습니다.

Install / 설치

Copy the skill folder into your Codex skills directory:

mkdir -p ~/.codex/skills
cp -R skills/pet-to-pixel-mascot ~/.codex/skills/

Codex skill 목록이 바로 갱신되지 않으면 Codex를 재시작하세요.

Restart Codex if the skill list does not refresh automatically.

Use With Your Pet / 내 반려동물로 사용하기

Codex에 반려동물 사진을 첨부하고 이렇게 요청하세요:

Use $pet-to-pixel-mascot to turn these pet photos into a 2D pixel mascot.
First analyze the pet's distinctive features, then propose 4 directions and wait for my choice.

한국어로 요청해도 됩니다:

$pet-to-pixel-mascot을 사용해서 이 반려동물 사진들을 2D 도트 캐릭터 마스코트로 만들어줘.
먼저 가장 특징적인 외형과 성격을 분석하고, 4가지 시안을 제안한 뒤 내가 고를 때까지 기다려줘.

시안을 고른 뒤:

Use $pet-to-pixel-mascot to create expression options for the selected mascot.
Keep the markings, scale, and palette consistent.

선택한 마스코트 기준으로 표정 시안을 만들어줘.
무늬, 크기, 색감은 유지하고 neutral, happy, sleepy, surprised 같은 표정을 제안해줘.

애니메이션을 만들 때:

Use $pet-to-pixel-mascot to make an idle blink GIF from the selected mascot frames.
The frame centers must stay fixed.

선택한 마스코트 프레임으로 idle blink GIF를 만들어줘.
프레임 중심점이 흔들리지 않게 고정해줘.

Assemble A Sample GIF / 샘플 GIF 조립

Install dependencies:

python3 -m pip install -r requirements.txt

Create a GIF from the public synthetic frames:

python3 skills/pet-to-pixel-mascot/scripts/assemble_gif.py \
  --frames "examples/synthetic/frames/*.png" \
  --out "tmp/synthetic-idle.gif" \
  --fps 4 \
  --scale 4 \
  --canvas-size 32x32 \
  --transparent \
  --stabilize bbox-center

Inspect center drift:

python3 skills/pet-to-pixel-mascot/scripts/inspect_animation.py \
  --file "tmp/synthetic-idle.gif" \
  --max-center-delta 1

Use a .webp output path for animated WebP:

python3 skills/pet-to-pixel-mascot/scripts/assemble_gif.py \
  --frames "examples/synthetic/frames/*.png" \
  --out "tmp/synthetic-idle.webp" \
  --fps 4 \
  --scale 4 \
  --canvas-size 32x32 \
  --transparent \
  --stabilize bbox-center

Add A QR Watermark / QR 워터마크 추가

공개 브랜딩 예시에는 QR 워터마크를 넣을 수 있습니다. GIF는 반투명 alpha를 완벽히 지원하지 않기 때문에, visible-pixels 모드는 투명 배경을 유지하면서 실제 보이는 픽셀 위에 QR 색상을 블렌딩합니다.

For public branding examples, add a QR watermark after the animation is stable. GIF does not preserve true semi-transparent alpha well, so visible-pixels blends the QR colors onto visible pixels while keeping the transparent background intact.

python3 skills/pet-to-pixel-mascot/scripts/watermark_qr.py \
  --file "output/uyu/uyu-idle-blink.gif" \
  --out "examples/uyu/uyu-idle-blink-watermarked.gif" \
  --url "https://github.com/doyeonjeong" \
  --qr-size 512 \
  --position center \
  --opacity 0.1 \
  --blend-mode visible-pixels

Use QR watermarks only for public assets the owner has approved. Do not watermark or publish private source photos.

소유자가 공개를 승인한 결과물에만 QR 워터마크를 넣으세요. 원본 사진이나 비공개 결과물은 공개하지 마세요.

Stabilization / 흔들림 안정화

Generated frame sheets can drift by a few pixels. The assembler keeps old behavior by default, and only stabilizes when requested:

--stabilize none
--stabilize bbox-center
--stabilize-anchor first
--stabilize-anchor average

Use bbox-center when the subject should stay visually fixed and only small facial details, eyes, ears, or tail motion should change.

프레임마다 캐릭터 위치가 조금씩 흔들리면 --stabilize bbox-center를 사용하세요.

Privacy / 개인정보와 원본 사진

Do not commit original pet photos or private generated outputs. This repo's .gitignore excludes common private folders, but always check git status --short before committing.

원본 반려동물 사진과 비공개 생성 결과물은 커밋하지 마세요. .gitignore가 기본 폴더를 막지만, 커밋 전 항상 git status --short를 확인하세요.

Recommended local-only folders:

• photos/ for private source photos
• input/ for private references
• output/ for generated results
• tmp/ for local script output

The approved public Uyu examples live in examples/uyu/. Private source photos, sprite sheets, frame experiments, and non-approved outputs stay in ignored local folders such as output/.

승인된 우유 공개 예시는 examples/uyu/에만 있습니다. 원본 사진, sprite sheet, 실험 프레임, 비공개 결과물은 output/ 같은 ignored 폴더에 둡니다.

QA Before Release / 배포 전 QA

python3 -m compileall skills/pet-to-pixel-mascot/scripts
python3 -m unittest
python3 skills/pet-to-pixel-mascot/scripts/inspect_animation.py --file tmp/synthetic-idle.gif --max-center-delta 1
python3 skills/pet-to-pixel-mascot/scripts/inspect_animation.py --file examples/uyu/uyu-idle-blink-watermarked.gif --max-center-delta 1
python3 skills/pet-to-pixel-mascot/scripts/inspect_animation.py --file examples/uyu/uyu-laptop-work-watermarked.gif --max-center-delta 1
git status --short
rg -n "OPENAI|ANTHROPIC|API_KEY|sk-|token|secret|password" .

Release State / 배포 상태

1.0.0 is ready when RELEASE_CHECKLIST.md passes and the owner explicitly approves any push, tag, GitHub release, or social post.

1.0.0은 RELEASE_CHECKLIST.md가 통과하고, 소유자가 push, tag, GitHub Release, SNS 공유를 명시적으로 승인한 뒤 공개 배포합니다.

License

MIT