Animated GIF
세 가지 도구, 하나의 조립 코어. 입력에 맞는 경로를 선택하세요.
| 입력 | 도구 | 모션 |
|---|---|---|
| ANSI 색상의 텍스트 프레임 | bin/ascii_gif.py | 프레임 시퀀스 |
| 사진 또는 이미지 폴더 | bin/pics_gif.py | 홀드, 크로스페이드, Ken Burns |
| SVG 또는 HTML 애니메이션 | bin/svg_gif.py | SMIL, CSS, 또는 프리셋 회전/펄스/페이드 |
모든 경로는 bin/gifkit.py를 공유합니다: 루프 전체에 걸친 단일 팔레트, 10ms 타이밍 그리드, 동일한 연속 프레임을 더 긴 지연으로 병합, 원자적 쓰기, 읽기-복귀 검증.
종속성
Pillow가 필요합니다. SVG와 HTML은 Node와 Playwright 및 Chromium 헤드리스 셸이 필요합니다.
python -c "import PIL; print(PIL.__version__)"
node -e "require('playwright')"
npx playwright install chromium --only-shell
모든 도구는 종속성 또는 입력이 누락되면 stderr에 FAIL ... 한 줄을 출력하고 1로 종료합니다. 동일한 인수로 재시도하지 마세요.
워크플로우
- 표에서 경로를 선택하세요. 아래 해당 섹션을 읽으세요.
- 작업 중인 프로젝트 내부에 명시적 출력 경로를 지정하여 도구를 실행하세요. 시스템 임시 디렉터리나 데스크톱에 쓰지 마세요.
- 출력된 요약(프레임 수, 지속 시간, 픽셀 크기)을 기록하세요. 출력된 경로는 검증된 GIF입니다.
- 시각적 작업의 경우 GIF를 열거나
--preview preview.png를 작성하여 보고 전에 정지 프레임을 검사하세요. - 절대 경로와 함께 중요한 설정(fps, 크기, 지속 시간, 모드)을 보고하세요.
ASCII 경로
입력은 텍스트 파일입니다. 프레임은 ---만 포함된 줄로 구분되며, 구분 기호 뒤에 선택적 지연 시간(ms)이 올 수 있습니다: --- 250. ANSI SGR 색상(30-37, 90-97, 38;5;n, 38;2;r;g;b)이 지원됩니다. .txt 파일 디렉터리는 이름순으로 정렬되어 각 파일이 하나의 프레임으로 읽힙니다.
python bin/ascii_gif.py frames.txt -o project/loader.gif --size 28 --delay 120
python bin/ascii_gif.py frames/ -o project/loader.gif --preview project/loader.png
--font는 고정폭 TTF 또는 TTC여야 합니다. 생략 시 일반적인 고정폭 글꼴이 자동 감지됩니다.--width와--height는 캔버스를 고정하고 텍스트 그리드를 중앙에 배치합니다. 둘 다 지정하거나 둘 다 생략하세요. 여러 샘플 간 크기를 일치시키는 데 사용합니다.--fg와--bg의 기본값은 어두운 캔버스에 밝은 텍스트입니다.--delay는 기본 프레임 지연 시간이며, 구분 기호 지연 시간이 프레임별로 이를 재정의합니다.- 프레임은 약 120열, 40행 이내로 유지하세요. 더 큰 캔버스는 긴 GIF를 만듭니다.
이미지 폴더 경로
파일은 자연 정렬(pic-2가 pic-10보다 먼저), EXIF 회전 처리 후 하나의 캔버스에 맞춰집니다.
python bin/pics_gif.py photos/ -o project/reel.gif --mode kenburns --fps 12 --hold 1.2 --transition 0.5 --width 800
python bin/pics_gif.py photos/ -o project/reel.gif --mode sequence --fps 10 --hold 0.8 --fit contain --bg "#101010"
sequence는 각 이미지를 홀드합니다.crossfade는 이미지 간을 혼합합니다.kenburns는 각 이미지를 천천히 확대하며 방향을 번갈아가며 적용합니다.--width는 캔버스 너비를 설정합니다.--height는 첫 번째 이미지의 종횡비가 기본값입니다.--fit cover는 채우기 위해 자르고,contain은--bg로 패딩합니다.--hold는 이미지당 초,--transition은 혼합 초,--zoom은 Ken Burns 종료 확대 비율입니다.- 800px, 12fps에서 100장의 사진 폴더는 큰 파일을 생성합니다. 먼저 너비나 fps를 줄이세요.
SVG 및 HTML 경로
도구는 .svg를 요청된 뷰포트의 페이지로 래핑하거나 .html을 직접 연 다음, 각 스크린샷 전에 모든 애니메이션을 명시적 시간으로 일시 중지 및 탐색합니다. 프레임은 벽시계 타이밍에 의존하지 않습니다.
python bin/svg_gif.py logo.svg -o project/logo.gif --duration 3 --fps 15
python bin/svg_gif.py logo.svg -o project/logo.gif --animate rotate --selector "#mark" --duration 2 --background "#0b0d12"
python bin/svg_gif.py page.html -o project/page.gif --width 960 --height 540 --duration 4 --fps 12
--animate가 없으면 SVG 또는 페이지가 SMIL 또는 CSS를 통해 자체 애니메이션되어야 합니다. 정적 그림은 프리셋이 필요합니다.- 프리셋:
rotate,pulse,fade. svg 루트 또는--selector에 적용됩니다. --width와--height의 기본값은 SVG의width/height또는viewBox입니다.--dpr 2는 뷰포트의 두 배로 캡처하여 텍스트를 더 선명하게 합니다. GIF는 픽셀 크기가 두 배가 됩니다.- JS 기반 캔버스 또는 WebGL 페이지는 이 도구로 구동되지 않습니다. 프레임 훅을 노출하는 페이지를 사용하거나 프레임을 미리 렌더링하고 gifkit으로 조립하세요.
공유 옵션
--colors최대 255. 팔레트가 단순하거나 파일 크기를 줄여야 할 때만 낮추세요.--dither none은 플랫 아트와 텍스트에 적합합니다.floyd는 그래디언트와 사진에 도움이 됩니다.--loop 0은 무한 반복입니다. 다른 값은 해당 횟수만큼 반복합니다.--preview PATH는 첫 번째 프레임의 PNG 정지 프레임을 작성합니다.- 동일한 입력, 설정 및 도구 체인에 대해 출력은 결정적입니다.
사용자 정의 프레임
모든 프레임 시퀀스는 동일한 코어를 사용할 수 있습니다. 프레임은 RGB이고 동일한 크기여야 하며, 지연 시간은 10ms 그리드의 ms 단위입니다.
import sys
sys.path.insert(0, "bin")
import gifkit
from PIL import Image
frames = [Image.new("RGB", (320, 180), (n * 20, 40, 90)) for n in range(12)]
gifkit.write_gif(frames, "project/gradient.gif", [100] * 12)
write_gif는 하나의 팔레트를 구축하고, 동일한 연속 프레임을 병합하며, 원자적으로 쓰고 결과를 검증합니다. 데이터 애니메이션, 생성된 다이어그램 또는 이러한 경로가 다루지 않는 모든 프레임에 이 경로를 사용하세요.
계약
- 도구는 출력 디렉터리에
<name>.tmp.gif를 쓰고, 파일을 다시 읽어 프레임 수, 지속 시간 합계 및 픽셀 크기를 확인한 후 이름을 바꿉니다. 실패 시 임시 파일을 제거하고 불완전한 대상 파일을 남기지 않습니다. - GIF는 모든 프레임에 대해 하나의 팔레트를 사용하므로 색상이 깜빡이지 않습니다.
- 동일한 연속 프레임은 더 긴 지연 시간을 가진 하나의 프레임으로 병합됩니다. 출력 프레임 수는 저장된 수입니다.
- 지연 시간은 10ms GIF 그리드에 있으며 최소 20ms입니다.
검증
경로 검사는 소스 저장소에 있습니다. 저장소 루트에서:
python tools/check.py
각 검사는 PASS, SKIP 또는 FAIL 한 줄을 출력합니다. 누락된 선택적 종속성은 기본적으로 건너뛰며, --strict는 모든 경로를 요구합니다. 검사는 scratch/checks 아래에 fixture를 생성하고 저장소에서 비밀, 절대 경로, 비ASCII 텍스트 및 CRLF 줄 끝을 스캔합니다.
제한 사항
- GIF는 8비트 인덱스이며 최대 256색으로 제한됩니다. 사진은 디더링 없이 밴딩 현상이 나타납니다.
- 뷰어는 짧은 지연 시간을 제한합니다. 프레임 지연 시간을 20ms 이상으로 유지하세요.
- 길고 높은 fps의 트루컬러 시퀀스는 APNG 또는 WebM이 더 좋습니다. 품질을 요청받으면 그렇게 말하세요.
- 메모리는 프레임 수와 캔버스 크기에 따라 증가합니다. 도구는 하나의 팔레트를 구축하는 동안 모든 프레임을 보유합니다.
- ASCII 글리프 적용 범위는 선택한 글꼴에 따라 다릅니다. 누락된 상자 또는 블록 글리프는 빈 상자로 대체됩니다.
형식 제약 조건과 이러한 기본값의 근거는 references/animated-gif-considerations.md를 참조하세요.
파일
bin/gifkit.py- 팔레트, 타이밍, 병합, 원자적 쓰기, 검증.bin/ascii_gif.py- ANSI 텍스트 프레임을 GIF로.bin/pics_gif.py- 이미지 폴더를 GIF로.bin/svg_gif.py- SVG/HTML 애니메이션을 GIF로.bin/render_frames.cjs- Playwright 프레임 캡처 도우미.references/animated-gif-considerations.md- 형식 노트.
저장소 검사 및 샘플 생성은 tools/에 있으며, 설치된 스킬 페이로드 외부에 있습니다.