src(.glb, 문서에 담김) + view(az·el·dist) · autoRotate · background · fit · 파트 바인딩 4종설명
glTF(.glb) 모델 하나를 화면에 얹습니다. 카메라와 같은 이유로 작화·썸네일에서는 정지 그림(포스터)이고, 운전 모드에서만 WebGL 이 붙습니다. 편집기는 손을 댈 때마다 슬라이드 DOM 을 통째로 바꾸는데, 그때마다 WebGL 컨텍스트를 새로 만들면 몇 획 긋는 사이에 브라우저가 줄 수 있는 컨텍스트(여덟에서 열여섯)를 다 써 버립니다.
모델은 문서 안에 담깁니다. 화면 파일 하나만 주고받으면 되고 링크가 끊길 일이 없습니다 — 대신 그만큼 문서가 무거워집니다.
포스터는 인스펙터에서 직접 올리는 칸이 아니라 지금 화면을 포스터로 저장 단추입니다. 지금 궤도 시점(az·el·dist)으로 한 프레임을 찍어 PNG 로 저장합니다. 시점을 바꾼 뒤에는 다시 구워야 작화 화면의 그림도 따라 바뀝니다.
파트 — 모델 안의 이름으로 바인딩을 건다. 다른 요소는 요소 전체가 바인딩의 대상이지만, 3D 모델은 모델 안의 노드를 대상으로 삼을 수 있습니다. glTF 를 만들 때 파트에 붙인 노드 이름(예: lamp, valve-01)이 곧 바인딩의 part 값입니다.
파트 이름은 저장하지 않습니다. 인스펙터의 파트 목록은 지금 문서에 담긴 모델을 그 자리에서 다시 읽어(운전 모드와 같은 파서로, 화면은 그리지 않고) 얻습니다. 모델러가 노드 이름을 바꾸면 목록도 즉시 바뀌고, 옛 이름을 가리키던 바인딩은 조용히 걸 곳을 잃습니다.
파트에 거는 바인딩은 넷입니다 — 색·표시·회전·강조. 무엇을 어떻게 바꾸는지는 파트 바인딩 에 있습니다.
작화 미리보기 — 이름이 어느 부위인지 눈으로 고른다. 3D 모델 요소를 고르면 인스펙터의 3D 모델 칸 위에 작은 미리보기가 뜹니다. 끌어 돌리고 휠로 확대할 수 있고, 파트 목록의 줄을 가리키거나 누르면 그 파트만 밝게 남기고 나머지를 흐리게 한 뒤 카메라를 그 파트에 맞춥니다. 거꾸로 미리보기에서 부위를 누르면 그 파트가 목록에서 골라지고, 같은 자리를 한 번 더 누르면 한 칸 위(그 부위를 담은 가지)로 오릅니다. 반투명 껍데기(차체 유리 같은)는 건너뛰고 그 안의 부위를 집습니다. 목록 위 검색 칸은 띄어 쓴 낱말이 모두 들어간 이름만 남깁니다(conn 12). 줄 끝의 · 2 는 그 파트에 걸린 바인딩 수입니다. 검색 칸 옆 걸린 것만 을 켜면 바인딩이 하나라도 걸린 파트만 남습니다. 바인딩 카드의 미리보기에서 고르기 를 누르고 미리보기에서 부위를 누르면 그 이름이 카드의 파트 칸에 들어갑니다.
미리보기에서 돌리기만 해서는 문서가 바뀌지 않습니다. 그 시점을 요소에 남기려면 이 시점으로 저장 을 누르세요(시점 숫자 칸에 적힙니다). 미리보기는 바인딩 값을 칠하지 않습니다 — 작화에는 실시간 값이 없습니다. 미리보기의 WebGL 은 요소를 고른 동안 하나만 켜지고, 선택을 풀면 바로 버립니다.
설정 항목
| 이름 | 값 | 기본 | 설명 |
|---|---|---|---|
| 모델 파일 | .glb | (필수) | glTF 바이너리 한 덩이. 문서 안에 담깁니다 — 이미지 요소와 같은 규칙. 원본 5.9MB 를 넘으면 삽입을 거절합니다. |
| 포스터 | 이미지(PNG) | (없음) | 작화·썸네일에 보일 정지 그림. 인스펙터의 지금 화면을 포스터로 저장 단추로 지금 궤도 시점을 찍어 만듭니다 — 직접 올리는 칸이 아닙니다. |
| 시점 | az·el·dist | 45° · 25° · 2.5 | 궤도 카메라. az·el 은 도(degree), dist 는 모델 반지름의 배수. |
| 자동 회전 | number(도/초) | 0(끔) | 운전 모드에서 초당 이 각도만큼 계속 돕니다. 스크롤 밖으로 나가 안 보이는 동안은 멈추고, 그동안 바뀐 값(파트 색·표시·회전)은 다시 화면에 들어올 때 반영됩니다. |
| 배경 | transparent \| color | transparent | 셸 배경. 테마 토큰(var(--sc-…))을 넣어도 됩니다. |
| 맞춤 | 맞춤(contain) \| 채움(cover) | 맞춤(contain) | 요소 영역에 모델을 맞추는 방식. |
동작
모델 용량 상한은 원본 5.9MB 입니다. 서버 에셋 하나에 8MB 를 주는데, 문서에는 base64 로 들어가 원본의 4/3 배가 되므로 실질 천장이 6MB 근방입니다. 여유를 두어 5.9MB 에서 끊고, 넘는 파일은 삽입 자체를 거절합니다 — 받아 두고 저장할 때 실패하면 무엇을 잃었는지 알 수 없기 때문입니다. gltf-transform 등으로 줄여서 넣으세요.
5MB 를 넘으면(거절되지 않아도) 인스펙터가 경고합니다. 삼각형이 많은 모델은 현장 태블릿 GPU 에서 프레임이 떨어질 수 있습니다 — 판단은 쓰는 사람의 장비에 달렸으므로 경고만 하고 막지는 않습니다.
포스터가 300KB 를 넘으면 인스펙터가 경고합니다. 512px 한 변으로 구우면 대개 수십 KB 인데, 이보다 크면 요소가 아주 크거나 그림이 복잡한 경우입니다. 화면 한 장에 3D 모델이 여럿이면 포스터 무게가 그 배로 문서에 얹힙니다.
압축은 meshopt(EXT_meshopt_compression)만 엽니다. Draco·KTX2 압축을 건 glTF 는 못 엽니다. meshopt 는 같은 모델을 몇 배 작게 만들어 5.9MB 상한 안에 더 큰 모델을 넣을 수 있습니다(예: gltf-transform meshopt 입력.glb 출력.glb). Draco·KTX2 는 디코더를 함께 싣지 않았기 때문에 읽기가 실패하고, 그 실패는 삼키지 않고 배지로 알립니다 — 내보낼 때 그 압축을 끄거나 meshopt 로 바꾸세요.
살아 있는 3D 는 화면 한 장에 최대 4개입니다. 브라우저가 동시에 주는 WebGL 컨텍스트가 한정돼 있어서, 다섯째부터는 컨텍스트를 만들지 않고 포스터만 보여 주며 오른쪽 아래에 상한 배지를 답니다. 5개 이상 필요하면 화면을 나누세요.
렌더 해상도는 화면에 보이는 크기를 따라갑니다. 창 크기를 바꾸거나 전체 화면·대형 모니터로 확대해 띄우면, 또 창을 화면 밀도가 다른 모니터로 옮기면 캔버스가 그 크기로 다시 그려져 흐려지지 않습니다. 다만 캔버스 하나가 한 변 4096 물리 픽셀, 전체 4K(3840×2160) 픽셀 수를 넘지 않게 묶여 있어서, 아주 큰 요소를 고해상도 화면에 크게 확대하면 그보다 선명해지지는 않습니다. 터치 화면의 손가락 확대(핀치 줌)는 따라가지 않습니다 — 핀치로 키우면 3D 만 흐려질 수 있습니다.
테마 토큰에 예비값이 없으면 파트가 안 칠해집니다. 파트 색(partColor 바인딩의 임계값 출력)에 var(--sc-…) 토큰을 쓸 때, 배경처럼 브라우저가 직접 CSS 로 풀어 주는 자리와 달리 3D 렌더러는 CSS 변수를 못 읽습니다. 예비값(var(--sc-bad, #ef4444) 처럼 쉼표 뒤 값)이 있으면 그것을 쓰고, 없으면 그 파트는 색이 걸리지 않은 채로 남습니다 — 파트에 쓰는 색 토큰에는 항상 예비값을 넣으세요.