Insights
AI가 자동으로 큐레이션·번역·정리하는 기술 동향 피드입니다.
PopBook Studio는 모든 과정용 PDF를 사용자의 자체 AI(API 키, 로컬 모델 등)와 연동하여 상호작용하는 3D 팝업 교과서로 변환하는 도구입니다. 각 학습 단원은 왼쪽 페이지의 개념/퀴즈 텍스트와 오른쪽 페이지의 종이 공예 3D 모델로 구성되어 있어 체험형 학습을 제공합니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 GitHub Claude Ecosystem의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기CI
License: MIT
Node 18.17+
PRs welcome
모든 과정용 PDF를 사용자의 자체 AI(API 키, 로컬 모델 또는 Claude Code와 같은 코딩 에이전트)를 사용하여 브라우저에서 상호작용하는 3D 팝업 교과서로 변환합니다. Techartist의 Every Joule에서 영감을 받았습니다.
Drop a PDF in the studio, build, open the book, turn a page, fill a race jar and drag the model slider
각 펼침(spread)은 하나의 학습 단원입니다. 왼쪽 페이지에는 개념, 핵심 공식, 어휘, 먼저 예측하기 퀴즈 및 플랩을 들어 올리는 방식의 답안이 인쇄된 텍스트가 있습니다. 오른쪽 페이지에는 아이디어가 작동하는 것을 직접 만져볼 수 있는 종이 공예(paper-craft) 3D 모델이 담겨 있습니다. 퀴즈를 풀고 모델의 모든 부분을 터치하면, 그 학습 단원에 스탬프가 찍힙니다.
개발자가 아니신가요? 초보자 가이드(PDF)에서는 코딩이 필요 없이 Node.js 설치, PopBook 다운로드, AI 연결 및 첫 번째 책 제작에 이르는 모든 단계를 설명합니다.
 |  |
 |  |
필요한 것은 Node.js 18.17 이상입니다.
git clone https://github.com/AlphaaCode/Popbook.git
cd Popbook
npm install
...
**http://localhost:5173**을 열고 다음 단계를 따릅니다:
레포지토리에는 두 권의 책이 포함되어 있습니다: 프랑스 병렬 컴퓨팅 과정인 calcul-parallele과 모든 씬 블록을 사용하는 blocks-demo입니다. 이들은 *당신의 책(Your books)*에서 열거나 직접 http://localhost:5173/viewer/?book=blocks-demo에서 열 수 있습니다.
AI는 3D 코드를 작성하지 않습니다. 대신 엄격한 형식으로 book.json이라는 하나의 파일을 작성합니다(prompts/system.md가 모델이 읽는 내용과 정확히 일치합니다). 수작업 엔진(hand-written engine)이 유효한 모든 책을 렌더링하기 때문에, 작은 모델을 사용하더라도 결과의 신뢰성이 유지됩니다.
PDF 페이지 → 모델/에이전트 → book.json → 검증 (최대 2회 복구 라운드 포함) → books/<슬러그>/ → 3D 뷰어
긴 범위는 배치(기본값 호출당 15페이지)로 전송되며 스프레드는 병합됩니다. 답변이 검증에 실패하면 오류와 이전 답변은 최대 두 번까지 모델로 돌아갑니다.
| 옵션 | 필요 항목 | 기본 모델 | 전송되는 내용 |
|---|---|---|---|
| Claude API | ANTHROPIC_API_KEY | claude-opus-5-5 | 페이지 범위(pdf-lib로 슬라이스된 실제 PDF 문서) + 추출된 텍스트 |
| ... |
키(Keys). .env에 넣거나 (.env.example 복사) 스튜디오에 붙여넣으세요. 붙여넣은 키는 해당 작업의 로컬 서버로만 전송되며 디스크에 절대 기록되지 않습니다. 이 브라우저의 localStorage에 보관하려면 이 컴퓨터에서 기억을 체크하세요.
모델(Models). 기본값은 .env에서 가져오며 (ANTHROPIC_MODEL, OPENAI_MODEL, GEMINI_MODEL, COMPAT_MODEL), 스튜디오에서 빌드별로 변경할 수 있습니다. 기본값은 PDF 또는 이미지 입력을 지원하는 각 제공업체의 현재 플래그십 모델입니다 (2026년 11월 확인 기준); claude-sonnet-5-5는 더 저렴한 Claude 옵션입니다. 강력한 모델일수록 특히 장면 블록을 선택하고 충실하며 간결한 텍스트를 작성하는 데 더 좋은 책을 만듭니다.
OpenAI 호환 기본 URL:
| 서버 | 기본 URL |
|---|---|
| Ollama | http://localhost:11434/v1 |
| ... |
로컬 에이전트(Local agents). 스튜디오는 사용자의 PATH에서 claude, codex, gemini를 찾아 리포지토리 폴더에서 실행합니다. 이들은 CLAUDE.md / AGENTS.md를 읽고, books/<슬러그>/book.json을 작성하며, 검사기를 실행하고 자체 오류를 수정합니다. 그들의 출력은 빌드 로그로 스트리밍됩니다. Claude Code는 `--permission-mode acceptEdits --allowedTools
⚠️ [IMG:N] 형식 토큰은 이미지 placeholder 입니다. 번역하지 말고 원래 위치에 그대로 유지하세요.
AI 없이 테스트하기: POPBOOK_MOCK=1 npm start를 실행하면 예제 책을 반환하는 Mock 제공자가 추가됩니다.
이 폴더를 Claude Code(CLI 또는 데스크톱)에서 열고 다음을 실행합니다:
/popup-book path/to/lesson.pdf 1-10
또는 모든 코딩 에이전트에게 "AGENTS.md를 따라 lesson.pdf의 페이지 1~10으로 팝업 책을 만들어라"라고 요청할 수 있습니다. 수동 작업 시:
node tools/pdf2pages.mjs lesson.pdf --pages 1-10 --out books/my-lesson # 페이지별 텍스트 + source.pdf
# prompts/system.md에 따라 books/my-lesson/book.json 작성
node tools/check.mjs books/my-lesson # OK가 될 때까지 반복
...
에이전트는 내장 블록으로 아이디어를 담을 수 없을 때 사용자 지정 장면(custom scenes), 즉 직접 만든 3D 모듈도 작성할 수 있습니다. CLAUDE.md에 키트 API가 문서화되어 있으며, books/blocks-demo/scenes/pendulum.js가 예시입니다.
| 블록 | 아이디어는… | 독자는… | 스탬프 대상 | :--- |
| race | 최대 4가지 케이스에서 A 대 B의 경쟁 | 시뮬레이션된 시계를 시작하며; 두 개의 유리병 선반이 채워지고 (입방 시간 경과), 카드가 경과 시간 및 기계당 %를 보여줍니다. | 각 아이템 ID |
| ... |
모델 표현식 (expr, when)은 작은 안전 평가기(lib/expr.js)를 사용합니다: 숫자, + − * / % ^, 비교 연산자, && || !, ?:, min max abs sqrt log log10 log2 exp pow round floor ceil sin cos tan, pi, e. eval은 사용할 수 없습니다.
[viewer/blocks.js]에 function myblock(sc, ctx) { … return { G, pops, update, controls, demo } }를 작성하고 이를 BLOCKS 내보내기(export)에 추가합니다. 펜과 잉크 같은 모양을 맞추기 위해 [viewer/kit.js]의 헬퍼 함수를 사용하고, 클릭 가능한 메쉬에는 userData = { tip, click, target }를 설정하며, 모든 스탬프 타겟에 대해 ctx.touch(id)를 호출합니다.[lib/validate.js]의 BLOCKS에 이름을 추가하고, switch 문에서 필드를 정규화하며, sceneTargets()로부터 해당 타겟 ID를 반환합니다.[prompts/system.md]에 JSON 예시, 제한 사항(limits), 인터랙티브 ID 및 "아이디어 → 블록" 테이블의 행과 함께 문서화합니다. 모델은 여기에 문서화된 내용만을 사용합니다.books/blocks-demo/book.json에 스프레드를 추가한 다음, npm test를 실행하고 뷰어에서 해당 스프레드를 엽니다.뷰어는 따뜻하고 줄무늬가 있는 햇빛 아래 책상 위에 놓인 펼쳐진 하드커버를 보여줍니다. 페이지를 넘기려면 ← → 또는 키보드 화살표를 사용하고, #p3은 스프레드로 깊이 연결(deep-links)하며, ▶ Demo는 카메라를 각 모델로 이동시키고 실행합니다. 진행 상황(스탬프)은 localStorage에 저장됩니다. 세로 모드나 휴대폰에서는 3D 모델이 위에 놓이고 그 아래로 학습 내용이 스크롤됩니다. 아랍어 및 기타 RTL 언어가 지원됩니다 ("lang": "ar"). 인터페이스 문자열은 [viewer/i18n.js] (en, fr, ar)에 있으며, 책은 `
server.js 로컬 서버 (프레임워크 없음), 127.0.0.1:5173, 모든 AI 호출 프록시
app/ 스튜디오
viewer/ engine.js (책, 카메라, 페이지 넘김, 왼쪽 페이지), blocks.js, kit.js, i18n.js
...
OLLAMA_CONTEXT_LENGTH=32768 ollama serve를 사용하고 기본 URL로 http://localhost:11434/v1을 사용하세요. 작은 로컬 모델은 종종 유효성 검사(validation)에 실패하므로, 호출당 페이지 수(pages per call)를 낮추거나 더 큰 모델을 사용하십시오.npm start를 실행하는 터미널의 PATH에 있어야 합니다. 먼저 그곳에서 claude --version (또는 codex, gemini)을 실행하고 한 번 대화형으로 로그인하십시오..cmd shim)는 셸을 통해 시작되며, 에이전트 프롬프트는 books/<slug>/PROMPT.md에 작성되므로 따옴표 처리가 필요 없습니다. 포트 5173이 사용 중인 경우: $env:PORT=5174; npm start (PowerShell) 또는 set PORT=5174 && npm start (cmd).chrome://gpu를 확인하거나 다른 브라우저를 시도해 보십시오.네트워크상의 모든 사람이 귀하의 키를 사용하여 빌드를 실행할 수 있다는 것을 이해하는 경우에만 HOST=0.0.0.0을 설정하십시오.
버그 보고, 새로운 씬 블록 아이디어, 번역 및 풀 리퀘스트(pull requests) 모두 환영합니다. CONTRIBUTING.md부터 시작하십시오. 질문은 Discussions로 가십시오. 보안 문제는 비공개로 보고해 주십시오 (참고: SECURITY.md). 변경 사항은 CHANGELOG.md에 나열되어 있습니다.
MIT입니다. LICENSE를 참조하십시오. Techartist와는 관련이 없으며, Every Joule은 이 디자인의 영감의 원천이었습니다.