Folio
Folio 패널은 자연사 박물관이 표본을 설명하는 방식으로 아이디어를 설명합니다. 마운트 위에 하나의 물체가 있고, 그 옆에 번호가 매겨진 키(key)가 있으며, 그 물체를 어떻게 봐야 하는지 알려주는 벽걸이 텍스트(wall text)가 있습니다. 여기서 물체는 여러분이 발명한 기기(벤치, 저울, 베틀, 증류기 등)로, 그 작동 부품이 아이디어를 수행합니다. 독자는 그것을 만질 수 있으며, 기기의 모든 수치는 계산됩니다.
세 가지 약속
- 메커니즘, 은유가 아닙니다. 기기는 아이디어 옆에 삽화로 서 있는 것이 아니라 아이디어를 수행해야 합니다. 그리기 전에 한 줄을 작성하십시오: "독자가 X를 하면, Y 부분이 움직이고, 그 움직임은 아이디어에서 Z입니다."
- 단일 숫자 소스. 작은 순수 모델이 모든 것을 계산합니다: 바늘 각도, 액체 레벨, 판독값, 키, 테이블. 페이지는 모델이 반환하는 것만 표시하므로 두 곳이 서로 다른 값을 가질 수 없습니다.
- 안내된 읽기. 좋은 그림에도 여전히 안내자가 필요합니다. 각 패널에는 키, 항목별 설명, 전체 작동 방식, 그리고 단순화된 부분에 대한 정직한 설명이 함께 제공됩니다.
시작하기
- 레포지토리에는 세 개의 참조 패널이 포함되어 있습니다. 패널 I(
examples/attention/, 분석 벤치로서의 주의력)은 개별 단계와 공식으로 구성된 아이디어를 위한 모델입니다. 패널 II(examples/heart/, 이중 펌프로서의 인간 심장)는 시간에 따라 실행되는 모든 것(매 프레임 통합되는 시뮬레이션, 연속 흐름, 단계, 각 주기 후 다시 그려지는 차트)을 위한 모델입니다. 패널 III(examples/grid/, 소형 전력망)은 전기, 자기 및 에너지 흐름을 위한 모델이며, 밴드(band) 대신 독립형 기계(터빈, 회전자 발전기, 변압기, 철탑, 마을)로 구성된 벤치를 위한 모델입니다. 패널 IV(examples/hashmap/, 분류 사무소로서의 해시 맵)은 알고리즘과 데이터 구조를 위한 모델로, 아이디어가 개별 연속 작업 시퀀스(삽입, 조회, 크기 조정)이며 각 작업이 시간 제약이 있는 일련의 동작(들기, 운반, 비교를 위해 담그기, 모든 카드를 새 위치로 옮기기)으로 확장되어 독자가 각 단계를 지켜볼 수 있습니다. 가장 가까운 것을 먼저 여십시오. - 가장 빠른 시작은 참조 패널을 복사하는 것입니다:
node scripts/new-plate.mjs <name>명령어는 패널 I에서examples/<name>/디렉토리를 만듭니다. 그런 다음 모델, 장면 및 텍스트를 교체하십시오. 작동하는 패널을 기반으로 구축하는 것이 빈 상태에서 시작하는 것보다 빠르고 안전합니다. - 공유 전시 스타일은
kit/folio-page.css에 있습니다. 패널의page.html은/*CSS*/를 자체<style>태그 안에 넣고 자신의 규칙만 추가합니다. node scripts/build-site.mjs는 모든 패널과 표지 페이지(site/index.html)를docs/디렉토리에 빌드하여 GitHub Pages에 바로 사용할 수 있는 웹사이트를 만듭니다. 패널을 추가하려면 거기에PLATES배열에 이름을 추가하고 표지에 카드를 추가하십시오.node scripts/build.mjs examples/<name> dist/<name>.html명령어로 패널을 하나의 독립 실행형 파일로 빌드하십시오.- 이 파일만 설치된 경우(레포지토리 없음), 부록에 도면 라이브러리가 있습니다.
folio-kit.js로 저장하십시오.
패널은 다섯 개의 파일로 구성됩니다:
| 파일 | 역할 |
|---|---|
folio-kit.js | 도면 라이브러리(공유, 패널별로 편집하지 않음) |
folio-live.js | 세 가지 뷰: 스테이지, 라이트 레이어, 오빗, 뷰 스위치(공유) |
model.js | 순수 모델; window에 하나의 객체를 배치합니다. |
plate.js | 기기: 정적 지오메트리, 라이브 슬롯, 입력 |
page.js | 키, 컨트롤, 벽걸이 텍스트, 원장(ledger); 패널의 이벤트를 수신합니다. |
page.html | /*KIT*/ /*MODEL*/ /*PLATE*/ /*PAGE*/ 플레이스홀더가 있는 마운트 및 스타일 |
페이즈 A: 개요(아직 그림 없음)
A1. 범위. 시작하기 전에 사용자에게 무엇을 제공할지와 대략적인 소요 시간을 알려주십시오:
| 범위 | 내용 | 일반적인 시간 |
|---|---|---|
| 스케치 | 기기 + 키 + 판독값, 벽걸이 텍스트 없음 | 1시간 미만 |
| 패널 | 전체 전시 페이지("X 설명"의 기본값) | 1시간 30분 ~ 3시간 |
| 시리즈 | 하나의 공유 벤치, 스케일 및 팔레트를 사용하는 여러 패널 | 먼저 목록에 동의한 다음 한 번에 하나씩 패널 제작 |
A2. 모델. 시각적인 것을 작성하기 전에 model.js를 작성하십시오. 실제 공식, 단위 및 크기를 수집하십시오. 일반 객체를 반환하십시오: 입력값과 페이지에 표시될 모든 수량을 출력합니다. Node에서 실행하고 몇 가지 경우를 출력하십시오. 지금 엣지 케이스(빈 집합, 마스킹된 행, 한계값)를 찾으십시오. 장난감 가중치나 샘플 데이터와 같이 발명된 것이 있으면 "이 표본에 대하여" 벽걸이 텍스트에 기록하십시오.
A2b. 시간에 따라 실행되는 모델. 아이디어가 프로세스(심장 박동, 대기열 비우기, 학습 곡선)인 경우 상태와 step(s, dt) 함수, 그리고 표시되는 모든 것을 반환하는 read(s) 함수로 작성하십시오. 그림을 그리기 전에 패널 II가 휴식 중인 성인(약 115/80 mmHg, 박동당 70 mL, 5 L/min)에 대해 수행한 것처럼 Node에서 알려진 값에 대해 매개변수를 조정하십시오. 시뮬레이션은 그림이 화면 밖에 있을 때도 계속 실행하고 페인팅만 건너뛰십시오. 그렇지 않으면 페이지 아래쪽의 컨트롤을 변경할 때 숫자가 멈춥니다.
A3. 기기 및 대응 테이블. 실험실, 작업장, 전망대 또는 인쇄소 세계의 기기를 찾으십시오. 그런 다음 각 용어를 부품에 연결하는 테이블을 작성하십시오:
| 아이디어의 용어 | 기기의 부품 | 독자가 볼 수 있는 것 |
|---|---|---|
| 쿼리 | 오버헤드 레일의 캐리지 | 질문하는 단어 위에 정차 |
| 스케일된 점수 | 단어당 다이얼 하나 | 바늘 위치 |
| 소프트맥스 | 하나의 밀봉된 저장소 | 기둥(column)은 저장된 것만 나눌 수 있음 |
| 마스크 | 캡이 있는 스톱콕 | 이후 단어는 차단됨 |
| 가중 합계 | 층상 퇴적물 트레이 | 각 층의 길이가 가중치 |
모든 행에는 부품이 필요하고 모든 주요 부품에는 행이 필요합니다. 몇 가지 신뢰할 수 있는 매핑: 고정 합계는 저장소, 지갑 또는 무게 주머니가 됩니다. 비교는 다이얼, 저울 또는 캘리퍼스가 됩니다. 선택은 밸브, 스위치 또는 포인트 레버가 됩니다. 누적은 층, 스택 또는 탈리(tally)가 됩니다. 정렬은 레일, 랙 또는 슈트가 됩니다.
페이즈 B: 벤치
B1. 인벤토리. 배치하기 전에 부품을 나열하십시오. 30~60개를 목표로 하십시오. 용도별로 그룹화하십시오: 용어 부품(테이블에서, 항목당 반복), 지지 부품(플린스, 발, 기둥, 레일, 칼라, 브래킷), 제어 부품(선택기, 널링(knurled) 손잡이, 레버), 마운트 세부 사항(카탈로그 판, 새겨진 라벨, 스케일 스트립, 나사). 아이디어의 대상이 되는 하나의 수량만 빨간색으로 표시됩니다.
B2. 밴드. 세계 좌표를 사용하십시오(x축은 벤치 방향, y축은 뷰어 방향, z축은 위쪽). 벤치를 뒤에서 앞으로 깊이 밴드로 나누고 각 밴드에 한 종류의 부품을 할당하십시오. 패널 I은 레일, 기둥, 스톱콕, 매니폴드, 다이얼, 트레이 순서로 실행됩니다. 밴드 사이에 여유 공간을 두십시오(세계 단위로). 부품이 다음 밴드로 튀어나오면 잘못된 순서로 페인팅되기 때문입니다. 밴드 내부에서는 먼 곳에서 가까운 순서로 그리십시오. 카메라(az는 긴 벤치의 경우 -24 근처, el은 30)를 설정하고 Folio.fit을 사용하여 모서리에 맞추십시오.
B3. 정적 문자열, 라이브 슬롯. 밴드를 한 번 순회하고 SVG 문자열을 정렬된 목록에 푸시하십시오. 움직이는 부분이 있으면 대신 이름이 지정된 슬롯을 푸시하십시오. 마운트 시 목록은 슬롯당 빈 <g> 요소가 있는 하나의 SVG가 됩니다. 각 애니메이션 프레임은 모델의 목표를 추적하는 이징(eased) 값에서 슬롯만 다시 그립니다. 모든 값이 도착하면 그리기가 중지됩니다.
B4. 핀. 아이디어를 담고 있는 부품에 6~10개의 번호가 매겨진 핀을 배치하십시오. 번호는 초보자가 봐야 하는 순서대로 매깁니다. 핀은 그림 위에 놓이는 유일한 표시입니다. 다른 모든 텍스트는 표면에 새겨집니다: 패드 전면의 이름, 스케일의 숫자, 플린스의 카탈로그 판.
페이즈 C: 마운트
페이지는 설명의 일부입니다. 다음 블록을 위에서 아래로 빌드하십시오:
- 마스트헤드(Masthead). 왼쪽에 시리즈 이름, 가운데에 워드마크, 오른쪽에 패널 번호.
- 제목 블록. 아이디어를 기기로 명명하는 디스플레이 제목(예: "분석 벤치로서의 주의력"), 발생하는 일에 대한 세 문장, 그리고 작은 카탈로그 목록(객체, 아이디어, 모델, 카탈로그).
- 마운트된 패널. 가는 실선 내부 프레임이 있는 종이 마운트. 모서리에는 패널 번호, 짧은 캡션, 상호작용 힌트 및 실시간 판독값이 있습니다.
- 키. 핀당 하나의 항목으로, 부품 이름과 계산하는 내용을 한 줄로 설명하며, 수학은 모노스페이스로 표시합니다. 항목 위에 마우스를 올리면 핀이 강조 표시되고, 핀 위에 마우스를 올리면 해당 항목이 강조 표시됩니다.
- 벤치에서. 기기 자체의 손잡이가 하는 것과 동일한 기능을 하는 일반 버튼과 슬라이더.
- 벽걸이 텍스트 I: 패널 읽기. 공식이 작성된 순서대로 용어당 하나의 열: 로마 숫자, 동사, 용어, 핀 번호를 참조하는 두 문장, 그리고 현재 숫자 상자.
- 벽걸이 텍스트 II: 원장. 현재 상태에 대한 완전한 계산 과정, 항목당 한 행. 행을 클릭하면 해당 항목이 선택됩니다.
- 벽걸이 텍스트 III: 더 넓은 시야. 기기가 보여주는 조각(전체 행렬, 전체 시퀀스, 모든 버킷)과 선택기가 선택하는 변형.
- 벽걸이 텍스트 IV: 이 표본에 대하여. 세 가지 노트: 정확히 계산된 것, 수동으로 선택된 것, 생략된 것. 항상 포함하십시오.
- 판권(Colophon). 패널을 만든 사람과 사용된 글꼴.
컨트롤은 포인터와 키보드에 응답합니다: 스테이션을 클릭하고, 화살표 키로 단계를 이동하고, 숫자 키로 변형을 선택하고, 대괄호로 손잡이를 돌리고, 한 글자로 토글을 전환합니다. 아무도 상호작용하지 않으면 패널은 천천히 자체 데모를 보여줍니다. 마우스를 올리거나 포커스가 있으면 일시 중지되고, 스크롤하여 벗어나면 정지하며, 축소된 모션에서는 한 개의 정지된 프레임을 표시합니다. 판독값은 aria-live를 사용합니다.
페이즈 C2: 세 가지 뷰
모든 패널은 동일한 기기를 세 가지 방식으로 제공하며, 마운트의 상단 모서리에 있는 작은 스위치(SVG · WebGL · 3D)에서 선택합니다. 모델, 키 및 벽걸이 텍스트는 뷰 간에 변경되지 않습니다. 변경되는 것은 벤치가 표시되는 방식뿐입니다.
SVG는 위에서 설명한 새겨진 그림입니다. 기본값이며 항상 작동해야 하는 유일한 뷰입니다.
WebGL은 그림을 다시 그리지 않고 그림 위에 빛을 배치합니다. 빛은 SVG 위에 있는 캔버스에 있으며, 그림 자체에서 렌더링된 마스크를 통해 보이는 것을 알고 있습니다. light()는 SVG를 복제하고, 역할별로 모든 표면의 색상을 다시 지정하고(바닥은 빨간색, 용기와 파이프는 녹색, 유리는 파란색, 나머지는 검은색), 화가의 순서를 유지한 다음 결과를 텍스처로 업로드합니다. 그림이 숨기는 것은 빛이 닿을 수 없으므로 별도의 폐색 논리가 필요하지 않습니다. 각 표면에 클래스(플린스에는 floor, 받침에는 pad, 용기에는 pipe 또는 혈액 클래스)를 지정하고 색상 규칙을 maskCss로 전달하십시오.
셰이더 내부에서 onPlane(vb, z)는 픽셀을 수평면의 세계 점으로 다시 변환하고, project()는 반대 방향으로 가며, fall()은 부품을 통과하는 빛이 바닥에 닿는 위치를 찾습니다(램프는 벤치 뒤에 있으므로 풀(pool)은 부품 앞, 독자가 볼 수 있는 곳에 떨어집니다). 주제 수량에 대해서만 빛을 사용하십시오:
- 패널 I: 각 기둥의 유체는 가중치로 빛나고, 주름진 빛 기둥이 각 기둥에서 벤치를 가로질러 흐르며, 매니폴드를 따라 펄스가 실행됩니다(가중치가 이동하는 동안 더 빠르게).
- 패널 II: 펄스는 진정한 흐름(SVG 흐름 표시를 움직이는 동일한 누적 부피)으로 모든 혈관을 따라 이동하고, 각 방은 혈액 색상의 빛을 발산하며, 심실은 수축할 때 플레어(flare)를 발생시킵니다.
빛은 미리 곱해진 색상(addLight)으로 누적되고 테마별로 색상을 선택합니다: 종이 위에는 옅은 하이라이트와 채도가 높은 풀(일반 블렌딩), 어두운 바탕에는 더 밝은 글로우(화면 블렌딩, --light-blend 토큰으로 설정). 뷰가 켜져 있고 패널이 화면에 있을 때만 렌더링하고, 픽셀 비율을 1.5로 제한하며, 축소된 모션에서는 하나의 정지된 프레임을 그립니다.
3D는 벤치를 완전히 회전시킵니다. 전체 장면은 카메라의 함수이므로 stage.mount(az, el)은 단순히 새로운 각도에서 장면을 다시 빌드합니다: 모든 면은 향하는 방향에 따라 다시 음영 처리되고, 모든 둥근 부품은 다시 실루엣 처리되며, 모든 해칭(hatch)은 다시 간격이 조정되고, 모든 새겨진 라벨은 다시 투영됩니다. 화가의 순서는 모든 측면에서 유지되어야 하므로 "뒤에서 앞으로"를 하드코딩하지 마십시오:
- 각 깊이 밴드를
{ y, draw }로 감싸고 목록을api.bands(list)에 전달하면 현재 카메라에 대해 먼 것부터 가까운 순서로 정렬됩니다. 뒤에서 보면 앞쪽 밴드가 먼저 그려집니다. - 밴드 내부 또는 분리된 기계로 구성된 벤치의 경우 각 유닛에 세계 위치를 지정하고
api.units(list)를{ at: [x, y, z], draw }와 함께 사용하십시오. 패널 III은 전적으로 이 방식으로 구축됩니다. - 열린 용기(트레이, 탱크)의 벽은
api.backIsFar및api.leftIsFar로 정렬됩니다. - 플린스의 한 면에 장착된 모든 것(놋쇠 카탈로그 판, 전면 패널의 타이밍 캠)은 해당 면이 독자를 향할 때만 그려집니다. 먼저
cam.view의 부호를 확인하십시오.faceText는 이미 자체적으로 컬링됩니다.
orbit({ wrap: true })는 방위각이 360°를 넘어 실행되도록 하고, stage는 각 각도에서 스케일을 다시 맞추며( orbitScale에 의해 제한되므로 벤치 크기가 절대 점프하지 않음), 더블 클릭하면 기본 뷰로 돌아가고, Shift 키와 화살표 키를 사용하여 키보드로 회전합니다. 두 고도에서 45° 간격의 각도 그리드로 확인하십시오. 패널 II의 전체 재구축은 약 27ms가 소요되므로 드래그하기에 충분히 부드럽습니다. 패널이 훨씬 무거운 경우 각 슬롯의 마지막 출력을 메모이제이션(memoize)하고 변경된 부분만 다시 페인팅하십시오(패널 III이 수행하는 방식).
3D를 떠나면 카메라는 기본 뷰로 돌아가므로 WebGL 라이트(기본 뷰를 가정함)가 항상 정렬됩니다.
페이즈 C2b: 움직이는 내부
패널은 옆에 숫자가 있는 정지 그림이 되어서는 안 됩니다. 실제로 움직일 부품을 찾아 눈이 따라갈 수 있는 속도로 모델에서 구동하십시오:
- 회전하는 것. 사이트 글라스의 흐름 바퀴는 진정한 흐름으로 회전하고(패널 I의 매니폴드), 타이밍 캠은 주기당 한 번 회전하며 활성 단계를 표시하고(패널 II), 발전기의 회전자, 물레방아, 플라이볼 조속기(flyball governor)는 기계의 속도로 회전합니다(패널 III). 시계가 아닌 모델에서 각도를 누적하므로(
rot += ω·dt) 느려지는 기계가 눈에 띄게 느려집니다. - 이동하는 것. 레벨, 피스톤, 판막 엽(valve leaflet), 바늘, 속도가 증가함에 따라 튀어나오는 조속기 볼, 차단기 블레이드 리프팅.
- 상호작용하는 것. 한 부품의 움직임이 다른 부품에 영향을 미칩니다(기어, 링크, 캠 종동자, 유체 흐름으로 인한 플로트 이동).
움직임은 이징 곡선을 따르므로 갑작스러운 시작/정지가 없으며, 각 슬롯은 현재 값, 목표 값 및 속도를 저장합니다. slot.tick(dt)는 목표를 향해 값을 업데이트하고 도착하면 true를 반환합니다. 모든 슬롯이 도착하면 그리기가 중지됩니다.
페이즈 D: 전시 페이지
페이지 레이아웃은 일관된 구조를 따릅니다. page.html은 다음 요소를 포함합니다:
<header>: 마스트헤드 및 제목 블록.<main>:<figure>(마운트된 패널),<section id="key">(키),<section id="controls">(벤치에서),<section id="wall-texts">(4개의 벽걸이 텍스트 블록).<footer>: 판권.
스타일은 kit/folio-page.css에서 공유되지만 page.html은 자체 <style> 블록에서 뷰별 스타일(예: 패널 테두리 색상, 핀 스타일, 벽걸이 텍스트 열 너비)을 재정의할 수 있습니다.
접근성을 위해 모든 상호작용 요소는 키보드로 접근 가능해야 하며, 판독값 업데이트는 aria-live 영역을 사용하고, 핀은 SVG <title> 요소를 가져야 하며, 모든 텍스트는 충분한 대비(최소 4.5:1)를 가져야 합니다.
페이즈 E: 테스트 및 배포
- 각 패널을 세 가지 뷰 모두에서 수동으로 테스트하고, 컨트롤이 모델 값을 업데이트하는지, 판독값과 키가 동기화되는지 확인하십시오.
- 엣지 케이스 테스트: 빈 데이터 세트, 극한값, 빠른 컨트롤 연속 클릭.
node scripts/build-site.mjs로 사이트를 빌드하고docs/디렉토리를 GitHub Pages에 푸시하거나, 단일 패널을node scripts/build.mjs examples/<name> dist/<name>.html로 내보내십시오.- 여러 패널로 작업하는 경우
page.html의 스타일이 충돌하지 않는지 확인하십시오(각 패널은 고유한<style>블록을 가져야 함).