OpenCAD STEP 뷰어·해석기

STEP(ISO 10303-21, AP203·AP214·AP242) 파일을 브라우저 안에서 읽고 B-rep 곡면을 삼각화해 3D로 보는 앱과 그 해석기입니다. 해석기는 DOM·WebGL에 기대지 않아 웹 워커에서 돌고, 결과 장면(Scene3d)은 opencad-viewer3d로 그립니다. 다른 CAD 커널이나 STEP 라이브러리를 쓰지 않고 공개 명세만 보고 새로 작성했습니다.

앱 주소(배포 예정): https://gyutae-kim.github.io/opencad-step/

함께 쓰는 저장소: opencad-viewer3d(3D 뷰어 코어) · opencad-nc · opencad-skp

할 수 있는 것

• Part 21 글 읽기(머리, 개체, 복합 개체, 문자열 부호)
• 압축 STEP: gzip(.stp.gz·.stpZ)과 안에 .stp·.step·.p21이 든 ZIP(저장·deflate, ZIP64) — unpackStep(src/archive.ts). STEP-XML(ISO 10303-28, .stpx)은 지원하지 않는다고 알려 줍니다.
• B-rep 곡면 삼각화: 평면·원기둥·원뿔·구·원환·B-스플라인·회전·밀기 곡면, 구멍 있는 면, 틈 없는 이음
• 조립(제품·인스턴스 변환), 색, 단위, 제품 나무(StepProductNode)
• 자리별 색 덮어쓰기(CONTEXT_DEPENDENT_OVER_RIDING_STYLED_ITEM): style_context(자리 변환 관계·NAUO·사상 항목)가 가리키는 자리에서만 칠한다
• 짧은 호(처진 높이가 허용 오차보다 작은 원호)도 두 토막 이상으로 나눠, 같은 꼭짓점을 잇는 현과 겹친 활꼴 면이 넓이 0으로 실패하지 않는다
• 레이어(PRESENTATION_LAYER_ASSIGNMENT, 레이어를 가리키는 INVISIBILITY) → meta.layers
• 제품 속성(제품 설명·판·정의 설명, 재질 이름·밀도, 사용자 속성 — PROPERTY_DEFINITION → 표현 항목, MATERIAL_DESIGNATION) → StepProductNode.props, 자리의 세계 변환 → StepProductNode.matrix(밀도는 단위를 따라 kg/m³로, 단위가 없으면 값 크기로 g/cm³·kg/m³를 짐작)
• 와이어프레임·곡선 형상(GEOMETRICALLY_BOUNDED_WIREFRAME_SHAPE_REPRESENTATION의 GEOMETRIC_CURVE_SET·GEOMETRIC_SET, EDGE_BASED·SHELL_BASED_WIREFRAME_MODEL, 형상 표현 안의 독립 곡선 — 선·원·잘린 곡선·복합 곡선·B-스플라인 등, 선 색 CURVE_STYLE) → scene.lines(점은 scene.points)
• 표현 PMI(ANNOTATION_CURVE_OCCURRENCE·TESSELLATED_ANNOTATION_OCCURRENCE 등, ANNOTATION_PLANE·DRAUGHTING_CALLOUT 안까지)를 그 부품 자리에 선으로, 의미 PMI(치수 값·± 공차, 기하 공차 크기·데이텀, 데이텀) 목록 → meta.pmi
• PMI 글자(TEXT_LITERAL과 아형, COMPOSITE_TEXT 안까지)를 내장 한 획 글꼴(src/strokefont.ts — 숫자·영문·기호 ± ° Ø ×·GD&T 기호)로 선분으로 그립니다. 글자 높이는 TEXT_LITERAL_WITH_EXTENT 크기, 주석 양식의 BOX_HEIGHT, 없으면 2.5. 맞춤(centre·right·top)을 따릅니다(src/pmitext.ts)
• 내장 글꼴에 없는 PMI 글자(한글·일본어·중국어·그 밖의 기호)는 앱의 해석 워커가 기기 글꼴로 화면 밖 캔버스에 그려 윤곽선을 따라간 선분으로 그립니다 (src/app/glyphs.ts·src/glyphtrace.ts — 글꼴 파일을 내려받지 않고, 글자마다 한 번만 그립니다). 다른 PMI 선과 같은 선 묶음이라 확대·단면·숨김·강조·그림 저장을 그대로 따릅니다. 해석기만 쓸 때는 glyphs 선택으로 글자 모양을 주고, 주지 않거나 기기에 그 글자 글꼴이 없으면 빈 상자로 그립니다
• 의미 PMI ↔ 면: 모양 측면 → GEOMETRIC_ITEM_SPECIFIC_USAGE → 면, 복합 측면·데이텀 ↔ 데이텀 형체는 SHAPE_ASPECT_RELATIONSHIP으로 따라가 semantic[].faces(면 STEP 번호)
• 저장된 보기(CAMERA_USAGE → CAMERA_MODEL_D3·VIEW_VOLUME·보기 창): 대상·방향·투영·창 높이와 그 제도 모형의 표현 PMI → meta.pmi.views(src/savedviews.ts)
• 면 표(그물 삼각형 → B-rep 면, 면 종류·곡면 매개변수, B-rep 넓이·둘레와 정확한지) → meta.faceTables·meta.meshFaceTable(면 단위 고르기)
• 모서리 표(그물 윤곽선 Mesh3d.edges의 선분 → B-rep 모서리 EDGE_CURVE, 곡선 종류 직선·원·타원·B-스플라인, 원 중심·법선·반지름·호 각, 곡선 길이 적분, 곡선 모서리 두 끝의 접선 — B-rep 곡선의 1차 도함수, 모서리 방향, 원호·타원 호의 틀 x축과 두 끝 매개변수 각(한 바퀴 원은 없음, 한 바퀴 타원은 틀 x축만)과 B-스플라인 정의 — 차수·매듭·조절점·가중치·모서리 매개변수 구간, 수 512개까지 curveStart·curves) → meta.edgeTables·meta.meshEdgeTable(모서리 고르기·개체 측정·측정 접선 잠금 — 이음선은 윤곽선에 없어 표에도 없음)
• 닫힌 입체(닫힌 껍질, 실패한 면 없음, 삼각형이 틈 없이 맞물림)의 그물에 Mesh3d.closed = true — 단면에서 잘린 면을 채웁니다
• 닫힌 입체의 질량 속성(부피, 1차·2차 모멘트)을 화면용 삼각형이 아니라 B-rep 곡면과 모서리 곡선을 적분해 구합니다 → 면 표 props(src/massprops.ts). 발산 정리로 입체 적분을 겉면 적분으로 바꾸고, 면마다 곡면 매개변수 공간에서 그린 정리로 경계 적분으로 바꿉니다. 평면·원기둥·원뿔·구·원환과 회전 곡면(직선·원·타원·B-스플라인 윤곽 — 윤곽이 축과 한 평면에 있지 않아도 됨)은 안쪽 적분이 닫힌 식이라 직선·원·타원 모서리로 된 입체는 반올림 오차 수준(상대 1e-14 안팎)으로 맞습니다. B-스플라인 윤곽은 매듭 구간마다 다항식이라 매개변수 공간 직선 토막을 매듭에서 나눠 적분합니다. B-스플라인 곡면과 B-스플라인 곡선을 민 곡면도 매듭 구간마다 (u, v)의 다항식이라, 안쪽 적분을 u 매듭에서 나눈 가우스로(u 구간이 많으면 다 덮는 구간 적분의 누적 합을 v의 다항식으로 미리 구해 둠), 매개변수 공간 직선 토막을 u·v 매듭에서 나눈 가우스로 정확히 구합니다. 모서리 곡선 토막은 곡선 매듭에서 나눠 7–15점 가우스–크론로드로 적분하고 둘이 어긋나면 반으로 나눕니다. 곡선 위 점은 토막 끝의 (u, v) 사이 짐작에서 가우스–뉴턴으로 곧장 곡면에 되짚고 (마지막 점의 편도함수를 그대로 쓰고, 반올림 수준에서는 걸음을 줄여 다시 구하지 않음), 곡면에서 되짚기 허용치보다 멀 때만 격자 짐작까지 합니다. 가중치가 있는 B-스플라인(NURBS)은 점을 더 쓰고 점이 적은 규칙과의 차이를 어림 오차로 남깁니다 (NURBS 원기둥에서 어림 오차 상대 3e-12, 실제 오차 1e-16). 원·타원을 민 곡면은 원기둥처럼 닫힌 식입니다. 오프셋 곡면처럼 적분하지 않는 곡면과 모서리 곡선이 곡면에서 멀어 곡면 적분의 어림 오차가 삼각형 쪽보다 큰 면은 그 면만 삼각형으로 재고 꺾인 선과 곡선 사이 띠를 더해 겉면을 닫으며, 삼각형과 곡면 사이 거리로 어림 오차를 함께 남깁니다. 삼각형 부피와 크게 어긋나면 삼각형 값으로 되돌리고, 적분이 오래 걸리면(기본 1.5초 + 삼각화 시간의 절반을 넘으면) 남은 입체는 삼각형 값과 어림 오차를 씁니다(propsBudget, meta.stats.propsTimedOut). 적분은 삼각화와 떼어 둡니다: 삼각화하면서 면마다 적분할 거리(곡면, 매개변수 공간 다각형, 경계 모서리와 곡선 매개변수)만 남기고 MassPropsJob(src/propsjob.ts)이 따로 적분합니다. 앱 워커는 문서를 보인 뒤 면 단위로 나눠 적분하고, stepToScene은 예전처럼 끝까지 적분한 장면을 돌려줍니다
• 닫힌 껍질의 면 방향 맞추기: 경계 고리가 면 법선과 거꾸로 돈 면(곡면 법선 약속이 다른 프로그램의 파일 — 예: 압출 곡면의 u·v를 바꿔 씀)이 있거나 부피가 음수면, 이웃 면이 같은 경계 선분을 같은 방향으로 쓰는지 보고 면 묶음을 뒤집어 바깥 법선으로 맞춥니다(orientFaces — 덩어리마다 부피 부호로 바깥을 정해 빈 곳 BREP_WITH_VOIDS는 안쪽으로). 단일면으로 그리는 닫힌 입체에서 면이 사라지지 않습니다
• 주기를 한 바퀴 다 덮으며 이음선을 갔다 오는 띠 고리(원환 필렛 고리 등)는 FACE_BOUND 방향이 거꾸로 적혀도 구멍이 아니라 그 띠로 읽습니다
• 큰 부품의 작은 반지름 필렛처럼 성긴 현 안쪽에 점이 생겨 삼각형이 접히면(3D 법선이 곡면과 반대), 안쪽 접힘은 나누고 경계 현 때문이면 그 면의 모서리를 더 잘게(현 높이 ¼, 두 번까지) 나눠 그 모서리를 쓰는 면만 다시 삼각화합니다(이웃 면도 같은 다각선이라 틈이 없음)
• 곡선 모서리 둘이 현 높이보다 좁게 나란히 가는 가는 띠 면처럼 경계가 스스로 엇갈려도 고리 점을 하나도 빼지 않고 삼각화해(clipAll — 엇갈린 자리의 삼각형은 뒤집히지만 띠 너비만큼이라 아주 작습니다) 이웃 면과 틈이 생기지 않습니다
• 한 변이 한 점으로 모인 곡면(극점)에서 극점으로 들어가는 두 경계가 같은 접선으로 만나 폭이 아주 빨리 0으로 모이면, 다듬기가 나눈 점들이 3D로 거의 겹쳐 바늘 같은 삼각형이 접히던 것을 막습니다: 극점 밖 두 점이 용접 거리의 10배보다 가까워지면 극점 둘레를 따로 떼어, 극점에서 곧게 나가는 빛살과 모든 빛살이 함께 쓰는 깊이 줄로 나누고 나머지만 다시 삼각화합니다. 경계 다각선은 그대로라 이웃 면과 틈이 없습니다(로컬 표본 "아주 세밀" 품질에서 감기가 어긋난 입체 4개 파일 → 0개, 같은 처리가 걸린 다른 6개 파일은 접힌 삼각형 6~11개 → 0개)
• 끊긴 파일(END-ISO-10303-21이 없거나 마지막 문장이 잘림)은 해석기 경고 맨 앞에 TRUNCATED_WARNING을 두고, 아는 곡면을 가리키는 개체가 없어 못 만든 면은 "지원하지 않는 곡면"이 아니라 "읽지 못함(가리키는 개체가 없거나 값이 잘못됨)"으로 적습니다
• 큰 좌표(좌표 크기 1e4 단위 이상이면서 묶음 크기의 2000배 넘음 — 예: 공장·지도 좌표 1e5~1e6 mm)에 만든 형상은 묶음 가운데를 origin으로 빼고 담아 float32로도 떨리지 않습니다(그 밖에는 예전과 같습니다)
• 틈·넓이·부피 검사(watertightness, meshArea, meshVolume)
• 공개 STEP 21개를 실패 면 없이 읽었고, NIST 시험 모형 9개는 모두 틈이 없습니다. 여러 CAD·커널이 내보낸 로컬 STEP 2,091개(내용이 같은 것 뺌)를 세 곡면 품질(20°·10°·5°)로 훑어(npm run sweep — 개발 절) 예외·실패 면 0, 닫힌 껍질 3,119개가 모두 틈 없이 닫히는 것을 확인했습니다(보통 품질에서 삼각형 감기가 어긋난 입체 72개 파일 → 0개, 접힌 삼각형이 0.1% 넘는 파일 35개 → 6개). 앱의 "아주 세밀" 품질에서 가장 오래 걸리는 파일(면 2,730개, 삼각형 274만 개)은 12초쯤 걸립니다(데스크톱, 고치기 전 20초). 같은 표본(보통 품질)의 닫힌 입체 3,114개 가운데 2,808개는 질량 속성이 곡면 적분으로 정확하고, 301개는 B-스플라인 같은 면이 섞여 어림 오차가 많아야 ±0.083%입니다(나머지 5개는 지름 0.4 µm 남짓한 퇴화 입체라 삼각형 값). 질량 속성은 문서를 연 뒤 따로 적분하므로 문서 여는 시간은 적분을 넣기 전과 같습니다(표본 442개를 번갈아 잰 합: 적분 없이 8.9초, 지금 9.1초, 열면서 함께 적분하면 11.9초). 회전 곡면도 적분한 뒤 지금 남은 표본 1,864개(보통 품질)에서는 근삿값 입체가 197개 → 177개로 줄었습니다(회전 곡면이 든 32개 파일 가운데 20개가 정확, 12개는 B-스플라인 면 등이 섞여 어림 오차만 줄어듦). B-스플라인·민 곡면까지 적분하자 근삿값 입체가 177개 → 166개(파일 147개 → 136개), 가장 큰 어림 오차가 ±0.083% → ±0.017%가 되었습니다. 값이 바뀐 입체 91개는 모두 예전 값 ± 어림 오차 안이고, 그 가운데 88개는 어림 오차가 좁아졌습니다(예: ±0.013% → ±0.00007%). 근삿값이던 그 파일들의 B-스플라인·민 곡면 642개 가운데 577개(가중치 있는 면 284개 가운데 264개)를 곡면 적분하고 65개는 삼각형 쪽 어림 오차가 더 좁아 삼각형으로 잽니다. 질량 속성 적분 시간은 그 147개 파일에서 합 3.1초 → 5.1초(중앙 7 → 13 ms, 가장 긴 파일 0.37 → 0.47초)이고 문서 여는 시간은 그대로입니다. 남은 근삿값은 대부분 모서리 곡선(교선을 맞춘 곡선)이 곡면에서 조금 떨어져 생긴 것이라, 곡선 위 점을 곡면의 가장 가까운 점으로 다듬은 자리를 면의 경계로 적분하고 그 경계에서 곡선까지 곧은 띠를 더합니다. 이웃 면도 같은 곡선까지 이으므로 겉면이 닫히고, 어림 오차는 곡선과 곡면 사이 거리를 반지름으로 한 관의 부피(모형의 허용 오차)로 줄어듭니다. 모서리 곡선이 꼭짓점을 조금(1e-4 mm 안팎) 비껴 지나 면 경계가 꼭짓점마다 끊긴 곳도 꼭짓점 둘레를 메워 잇습니다. 그러자 근삿값 입체가 166개 → 29개(파일 136개 → 19개), 가장 큰 어림 오차가 ±0.017% → ±0.000011%가 되었습니다. 값이 바뀐 입체 292개(파일 284개)는 모두 예전 값 ± 어림 오차 안입니다. 적분 시간은 근삿값이던 136개 파일에서 합 3.5초 → 4.1초(중앙 7.0 → 7.5 ms, 가장 긴 파일 0.38 → 0.42초)입니다. "아주 세밀" 품질에서도 시간 한도를 넘는 파일이 없고(한도를 가장 많이 쓴 파일이 31%), 값은 보통 품질과 어림 오차 안에서 같습니다(B-rep 입체 2,887개의 상대 차 중앙값 1e-15). 시간 한도(1.5초 + 삼각화 시간의 절반)는 입체를 시작할 때 보므로 입체가 하나인 파일은 한도에 걸리지 않고 끝까지 적분합니다(적분이 가장 긴 두 파일이 그렇습니다). B-스플라인 면 적분에서 곡선 위 점 되짚기를 다듬자(점마다 곡면 계산 8번쯤 → 3번쯤) B-스플라인 면이 많은 파일의 적분 CPU 시간이 3039% 줄었습니다 (가장 긴 두 파일이 이 컴퓨터에서 0.500.53초 → 0.34~0.37초, 고치기 전·후를 번갈아 세 번 잰 가운데 값). 표본 전체로는 적분 CPU 시간 합이 11% 줄었고, 닫힌 입체 2,892개의 부피·무게중심·관성은 모두 예전 값과 상대 1e-14 안입니다(구한 길도 그대로). 보통 품질에서 한도를 가장 많이 쓴 파일은 입체 81개짜리로, 마지막 입체를 시작할 때 0.54초를 써 한도(2.64초)의 20%입니다. 한도가 삼각화 시간을 따라 늘어나서, 기기가 고르게 느리면 마지막 입체를 시작할 때까지 쓴 시간이 삼각화 시간의 절반을 넘는 파일만 걸릴 수 있습니다. 로컬 표본 1,860개에서 그런 파일은 둘이고(입체 9·13개), 그 둘도 이 컴퓨터보다 48배 넘게 느린 기기에서야 남은 입체가 삼각형 값이 됩니다.

앱 쓰는 법

• 열기: 제목 막대의 "열기"(Ctrl+O)로 .stp·.step·.p21 파일이나 압축 STEP(.stp.gz·.stpZ·STEP이 든 .zip)을 고르거나, 창 어디에나 끌어다 놓습니다(여러 개를 놓으면 첫 STEP 하나). 압축은 워커가 "압축 푸는 중" 단계로 풀고, 정보 탭에 압축 형식·ZIP 항목·푼 크기를 보입니다. .stpx(STEP-XML)는 지원하지 않는다는 안내가 뜹니다. 같은 Part 21 글인 IFC(건축 BIM, FILE_SCHEMA가 IFC…)는 다 읽기 전에 IFC 뷰어로 열라고 알리고, 끊긴 파일은 형상이 없으면 그것을 까닭으로, 일부만 읽혔으면 "파일을 다시 받아 여십시오" 알림을 띄웁니다. "예제 열기"는 우리가 만든 작은 조립 모형(받침판·블록 둘·핀 묶음, 레이어 셋, 받침판 PMI)을 엽니다. 한 번에 문서 하나를 열며 새로 열면 바꿉니다. 큰 파일은 해석 중 덮개의 "취소"(또는 Esc)로 멈출 수 있습니다.
• 파일은 이 브라우저 밖으로 나가지 않습니다. 읽기(웹 워커)와 그리기(WebGL2)를 모두 이 컴퓨터에서 합니다.
• 최근 문서: 파일 고르기·끌어다 놓기로 잘 연 파일은 이 브라우저의 IndexedDB(opencad-step — 목록 recent, 파일 recent-data)에 새것부터 8개까지 남깁니다(60MB보다 큰 파일과 예제·?open= 주소로 연 것은 빼고). 시작 화면의 "최근 문서"에서 이름·크기·시각을 보고 눌러 다시 열며, ✕로 하나씩 또는 "모두 지우기"로 지웁니다. 서버로 보내지 않고, 비공개 창처럼 저장소를 못 쓰면 목록 없이 그대로 씁니다. 목록을 그릴 때는 파일 바이트를 읽지 않고, 누른 파일 하나만 읽습니다. 저장해 둔 파일이 없으면 목록에서 지우고, 잠깐 못 읽으면 항목을 남겨 다시 누를 수 있게 합니다. 휴대폰 브라우저가 뒤로 간 탭을 버렸다가 다시 불러와도 파일 앱을 다시 거치지 않고 엽니다.
• 정면으로 보기·홈 뷰: 고른 면을 작업 메뉴의 "정면으로 보기"(휴대폰 면 고르기 띠의 "정면")로 평면은 바깥 법선 쪽에서, 원기둥·원뿔·원환은 축 방향에서 맞춰 봅니다. 표준 뷰 메뉴의 "홈 뷰"(Home 키)는 문서를 처음 열 때 맞춘 보기로, "지금 보기를 홈 뷰로"는 지금 보기를 홈 뷰로 정합니다.
• 보기: 왼쪽 끌기 회전, 오른쪽·가운데 끌기 이동, 휠 확대, 터치 회전·핀치. 도구 막대에 전체 보기(F), 고른 부품 보기, 표준 뷰(1 앞 · 2 뒤 · 3 왼쪽 · 4 오른쪽 · 5 위 · 6 아래 · 7 등각), 원근/평행, 그리기 모드(음영·음영+모서리·와이어프레임·X-ray·숨은선 제거·단색), 단면, 격자(F7), 뷰 큐브, 좌표축, 고르기(부품·몸체·면·모서리, 여러 개), 측정(두 점·개체, Esc = 지우기), 내보내기, 패널 열고 닫기가 있습니다. 그리기 모드 메뉴(휴대폰은 보기 설정)의 선택: 숨은 모서리 점선(숨은선 제거 모드에서 면 뒤 모서리를 흐린 점선으로 — 코어 setRenderOptions({ hiddenEdges })), 외곽선 강조(화면 공간 실루엣 — profiles), 부품 색 구분, 분해 보기(아래). 와이어프레임·숨은선 제거는 B-rep 모서리만 그리고(삼각형 변 없음 — 코어 triangleEdges) 모서리와 같은 1화소 외곽선을 늘 켭니다(코어 v0.7.2 profiles: { width: 1 }). 모서리가 없는 매끈한 면(원환 고리·구)도 테두리로 보이고, 이 두 모드에서 "외곽선 강조"는 켜진 채 잠깁니다(다른 모드로 가면 고른 값으로). 키는 캔버스에 초점이 없어도(입력 칸 제외) 듣습니다. Tab 키로 3D 보기에 초점이 오면 보기 안쪽에 테두리가 보입니다. 마우스·터치로 누르면 테두리가 사라지고(키보드로 초점을 준 뒤 눌러도), Tab으로 다시 오면 보입니다(코어 v0.9.1).
• 고르기 단위: 도구 막대의 "고르기" 메뉴(단추 이름이 지금 단위 — "부품 고르기"·"몸체 고르기"·"면 고르기")에서 부품(기본 — 누른 형상이 놓인 나무 마디 통째), 몸체, 면·모서리(아래 "면 고르기")를 고릅니다. 몸체는 한 부품 안에 입체(MANIFOLD_SOLID_BREP·BREP_WITH_VOIDS·면 모형 등 형상 항목)가 여럿일 때 누른 입체 하나만 고릅니다. 해석기가 형상 항목마다 그물 하나를 만들므로 해석 결과는 그대로입니다. 이름이 없는 몸체는 "부품 · 몸체 2"로 부릅니다. 숨기기·이것만 보기·맞춰 보기·STL/OBJ "고른 것"·속성 탭의 물리 속성(그 몸체만)에 그대로 쓰입니다. 부품 단위로 3D에서 누르면 그 부품의 몸체를 모두 강조합니다(숨기기·격리가 쓰는 것과 같게).

해석기 쓰는 법

import { stepToScene } from 'opencad-step';

const scene = stepToScene(bytes, {
  name: 'part.step',
  onProgress: (fraction, stage) => console.log(fraction, stage),
  // 선택(모두 기본 true): curves — 와이어프레임·곡선 형상, pmi — 표현 PMI 선·의미 PMI, faceTable — 면 표
  // glyphs?: (ch) => { strokes, advance } | null — 내장 획 글꼴에 없는 PMI 글자(한글 등)의 모양(글자 칸: 대문자 높이 6, 기준선 0). 없으면 빈 상자
});
// scene: Scene3d (opencad-viewer3d의 Viewer3d.setScene에 넘긴다), scene.meta에 제품 나무·단위 등
// scene.lines: 곡선 형상(group = 부품 이름, 나무 마디의 lineIds)과 표현 PMI 선(group 없음, meta.pmi.presentations의 id)
// meta.layers?: 레이어(이름·설명·처음 보이기·meshIds·lineIds) — Mesh3d.group은 그대로 부품 이름
// meta.pmi?: { presentations, semantic }
// meta.faceKinds·faceTables·meshFaceTable?: 그물 삼각형 → B-rep 면(src/brep.ts FaceTableData)
// meta.edgeKinds·edgeTables·meshEdgeTable?: 윤곽선 선분 → B-rep 모서리(src/brep.ts EdgeTableData) — 곡선 정의는 edgeCurve(표, 번호, edgeKinds)로 읽고
//   nearestOnCurve(정의, 점)로 곡선 위 가장 가까운 매개변수·점·접선을 구한다(src/edgecurve.ts, 좌표는 묶음 origin을 뺀 그물 좌표)
// faceTables[i].props?: 닫힌 입체의 질량 속성 [부피, 1차 모멘트 3, 2차 모멘트 6, 기준점 3, 부피 어림 오차, 구한 길](src/massprops.ts PROPS_*)
//   — 선택 props: false로 끄고, propsBudget: { minMs, share }로 적분 시간 한도를 바꾼다
// Mesh3d.closed: 닫힌 입체(단면 채우기) · Mesh3d/LineSet3d/PointSet3d.origin?: 큰 좌표일 때 묶음 원점(positions는 원점 기준)
// scene.warnings?.[0] === TRUNCATED_WARNING(같은 입구에서 가져옴)이면 끊긴 파일

// 질량 속성을 나중에 구하기: 장면을 먼저 쓰고, 적분은 조각으로 나눠(run(ms)이 true면 끝) 면 표에 넣는다
import { applyProps, stepToSceneDeferred } from 'opencad-step';
const { scene: shown, props } = stepToSceneDeferred(bytes);
while (props && !props.run(40)) applyProps(shown, props.take(), props); // 사이사이 다른 일
if (props) applyProps(shown, props.take(), props);

// 압축 STEP(gzip·ZIP)은 먼저 푼다(비동기, DecompressionStream)
import { unpackStep } from 'opencad-step';
const { bytes: step } = await unpackStep(fileBytes);

구조

경로	내용
index.html, public/	앱 진입 페이지, 아이콘, 앱 정보(공유 받기·파일 열기)
tools/site.mjs, tools/sw-source.mjs	이 앱의 사이트 설정(앱 정보 원본·서비스 워커 판 이름 짓기 — vite.config.ts와 시험이 같이 씀)과 오프라인 서비스 워커 본문(미리 담은 것 쓰기·공유 받기). 언어 페이지·검색 정보·사이트맵·언어별 앱 정보·dist/sw.js는 공용 사이트 도구의 Vite 플러그인이 이 설정으로 만든다
site/i18n-core.mjs, site/i18n.mjs, site/locales/	공용 번역기에 이 앱의 사이트 정보(site/metadata.json)를 넘기고 사전을 넣는다
src/app/main.ts, src/app/app.ts, src/app/core.ts	앱 진입점과 화면 골격(제목 막대·보기 도구 막대·3D 보기·패널·상태 막대), 열기·고르기·면 고르기·보이기·키, 3D 뷰어 코어·곡선 접선 잠금 나눠 받기
src/app/toolbar.ts, src/app/panel.ts, src/app/sectionbar.ts, src/app/dialog.ts, src/app/resize.ts, src/app/menu.ts, src/app/dom.ts, src/app/icons.ts, src/app/styles.css	보기 도구 막대, 제품·속성·레이어·PMI·정보 패널, 단면 막대·손잡이, 대화 상자, 패널 크기 손잡이, 메뉴(단추 아래·화면 점), DOM 도우미, 아이콘, 스타일
src/app/edges.ts, src/app/entmeasure.ts, src/app/entpick.ts, src/app/looks.ts, src/app/explode.ts, src/app/explodebar.ts, src/app/snap.ts, src/app/tangent.ts, src/app/curvesnap.ts, src/app/facesnap.ts	순수 로직: 모서리 찾기·길이·원 중심·붙잡기, 두 개체 사이 해석적 거리·각, 누른 것 → 개체·최소 거리·덧그림, 부품 겉모습(불투명도·흐리게·부품 색·분해 이동 걸기), 분해 계획(조립 단계별·한꺼번에 — 방식 단추·단계 글과 함께 문서를 열 때 받음), 두 점 측정 붙잡기 선택(원·원호 중심, 모서리 가운데 점, 추론 붙잡기)과 붙잡은 종류 이름, 곡선 모서리 위(끝·가운데)의 접선 잠금과 측정 붙잡기 점을 B-rep 곡선 위로 다듬기(수직 발·모서리 위 점·두 곡선의 교차점·축과 곡선의 교차)·곡선 길이 가운데 점, 축이 면을 뚫는 점을 B-rep 곡면 위로 다듬기(셋 다 문서를 열 때 받음)
src/app/doc.ts, src/app/tree.ts, src/app/faces.ts, src/app/visibility.ts, src/app/format.ts, src/app/display.ts, src/app/files.ts, src/app/keys.ts, src/app/theme.ts	순수 로직: 문서 모델·meta 읽기·다시 삼각화 때 상태 잇기·고르기 단위(부품·몸체)와 여러 개 고르기, 제품 나무 펼침·고르기·이름 거르기, 면 찾기·경계·넓이·PMI 면 범위, 보이기(눈 단추·레이어·PMI·격리), 글 만들기, 표시 설정(단위·소수 자리·곡면 품질·수 꼴), 파일 이름·주소 인자, 키 규칙, 테마

개발

npm install
npm run dev        # http://localhost:4402/ (예제 바로 열기: /?sample)
npm run typecheck
npm test           # 해석기 시험(tests/*.test.ts)과 앱 순수 로직 시험(tests/app/)
npm run build      # tsc --noEmit && vite build → dist/
npm run preview    # 빌드 결과 보기

시험은 tests/stepText.ts(본문은 src/app/stepText.ts)로 만든 작은 STEP 글로 돌립니다(외부 STEP 파일은 넣지 않습니다). 측정 방향 잠금 시험(tests/app/measurelock.test.ts)은 가짜 DOM·WebGL2(tests/app/fakeview.ts — 코어 저장소의 시험 도구를 줄여 옮김)로 실제 코어 뷰어를 만들어 앱의 붙잡기 선택과 포인터·키 사건을 넣고 코어가 잠그는 방향을 봅니다. 곡선 접선 잠금 시험(tests/app/measuretangent.test.ts)도 같은 방식으로 원기둥 테두리 원·타원 호·B-스플라인 모서리(tests/app/curvescene.ts)의 끝과 가운데(테두리 30° 지점·타원 호 가운데 점·B-스플라인 중간 꼭짓점)에서 앱이 코어보다 먼저 잠그는 접선을 봅니다. 곡선 위 가장 가까운 매개변수는 곡선 위 점에서 조금 비킨 점으로 1e-9 안에 맞는지 봅니다(tests/edgecurve.test.ts). 측정 붙잡기 다듬기 시험(tests/app/measurerefine.test.ts)도 실제 코어로 B-스플라인 판 모퉁이에서 원기둥 테두리로 내린 수직 발이 원 위 1e-9이고 거리 값도 그 발까지인지, 타원·B-스플라인 토막 위 점이 곡선 위인지, 직선 모서리는 그대로인지, 곡선 길이 가운데 점, 다듬은 첫 점·커서 아래 점에서의 접선 잠금을 봅니다 (순수 계산 — 꼭짓점 매개변수, 법선으로 비킨 첫 점의 발, 광선이 지나는 점, 곡선 길이 가운데 — 은 tests/app/curvesnap.test.ts). 코어 0.15.0 다듬기 시험(tests/app/measurecross.test.ts)은 원기둥 테두리와 3D로 한 점에서 만나는 곧은 모서리·세로 원·B-스플라인과 멀리 떨어진 판(tests/app/crossscene.ts)에서 꺾은선 토막에 내린 발이 모두 토막 밖인 먼 첫 점의 원 위 발과 거리, 세 교차점과 거리가 1e-9 안인지, 곡선 붙잡기가 없으면 두 후보가 없는지를 실제 코어로 봅니다 (순수 계산 — 교차점 식·가우스–뉴턴, 같은 평면의 직선과 원, 비켜 지나가는 둘·같은 모서리·함께 쓰는 꼭짓점·두 곧은 모서리는 없음, 열린 수직 발 — 은 tests/app/curvecross.test.ts). 코어 0.18.0 시험(tests/app/measureaxis.test.ts)은 원기둥과 옆 삼각 판에서 첫 점 X·Y축과 테두리의 교차가 원 위이고 축 위 정확히인지, 곡선 붙잡기가 없으면 현 위 점, 두 선택을 끄면 후보가 없고 첫 점 전에는 켜도 같은지, 끌어온 축과 테두리의 교차, 첫 점 X축이 옆면을 뚫는 점을 실제 코어로 봅니다 (순수 계산 — 원·곧은 모서리·타원·B-스플라인과 축의 교차, 비켜 지나가는 축·호 범위 밖 — 은 tests/app/axisedge.test.ts, 축·잠근 선이 B-스플라인에 접하는 자리 — 접점, 평평한 곡선, 허용치 밖·안 틈, 두 근, 접점이 모서리 끝 바로 밖 — 은 tests/app/axistouch.test.ts). 거리 글상자가 비킬 자리 시험(tests/app/labelavoid.test.ts)은 3D 보기의 측정 띠·위 띠·단면 막대·뷰 큐브만 고르는지, 크기가 바뀌면 다시 알리고 정밀 조준 자리와 합치는지, 헤드리스에서 잰 휴대폰 띠·큐브 자리를 코어 자리 고르기(placeMeasureLabel)에 넘기면 가리던 글상자가 비키고 겹치지 않던 자리는 그대로인지를 봅니다. 코어 0.19.0 시험(tests/app/measurelockface.test.ts)은 같은 장면에서 잠근 X·Y축과 테두리의 교차가 원 위인지, 잠근 X축과 잠그지 않은 첫 점 X축이 옆면을 뚫는 점이 원기둥 위인지, 축이 아닌 방향으로 잠근 선이 테두리와 만나는 점·옆면과 B-스플라인 지붕을 뚫는 점이 곡선·곡면 위인지(0.20.0), 두 선택을 끄면 0.18.0 그대로이고 잠그지 않았을 때는 켜도 같은지, B-스플라인 지붕과 민 곡면 원기둥(tests/app/facescene.ts)에서 워커가 남긴 곡면 정의로 곡면 위인지를 실제 코어로 봅니다(순수 계산 — 원기둥·원뿔·구·원환 식, B-스플라인·밀기·회전 곡면의 뉴턴법, 극점 둘레 다시 풀기와 먼 근·비켜 가는 직선, 단위 배율·묶음 원점, 곡면 정의 복제·되살리기, 잘린 면의 경계 — 은 tests/app/facesnap.test.ts, 워커가 들고 있는 곡면 정의의 격자 버리기는 tests/app/propsflow.test.ts). 코어 0.20.0 시험(tests/app/measureopen.test.ts)은 기울인 원판·타원 판·B-스플라인 판 위 점(한 토막 가운데 매개변수) 위 판 꼭짓점의 Z축이 곡선 평면을 뚫는 자리를 열린 교차로 곡선 위에 붙이는지(잠근 Z축도, 곡선 붙잡기가 없으면 교차 없음), 축이 아닌 방향·곡선 접선으로 잠근 선이 원 테두리와 만나는 점이 원 위인지를 실제 코어로 봅니다. 질량 속성 시험(tests/massprops.test.ts)은 해석적 입체와 비선형·비튼 매개변수 B-스플라인 평면 상자, 위가 B-스플라인인 블록, B-스플라인 곡선을 민 기둥, 이음선 모서리 없는 닫힌 B-스플라인 관, NURBS 원기둥을 닫힌 식과 견줍니다(안쪽 적분이나 직선 토막을 매듭에서 나누지 않으면 실패하는 입체를 함께 둡니다). 모서리 곡선이 곡면에서 떨어진 원기둥·구 조각·B-스플라인 관과 곡선이 꼭짓점을 비껴 지나는 반원 기둥도 닫힌 식과 견줍니다(띠나 꼭짓점 메우기를 빼면 실패합니다). 물결 친 B-스플라인 조각 위 (u, v) 원을 경계로 한 면은 극좌표 가우스로 구한 정확한 값과 견주고, 곡선 위 점마다 곡면 계산이 4번 밑인지(예전 길은 5.3번), 곡선이 곡면에서 되짚기 허용치보다 멀면 격자 짐작까지 해도 같은 값인지, 닫힌 B-스플라인 입체를 적분하는 동안 곡면의 되짚기를 부르지 않는지 봅니다. 압축 시험은 (시험용 ZIP 글쓴이, node:zlib)로 gzip·ZIP을 만듭니다. 확인용으로 받은 공개 STEP 파일이나 임시 결과는 git이 무시하는 에만 둡니다. 3D 뷰어 코어는 으로 받습니다 — 올릴 때는 처럼 태그를 주어야 잠금 파일의 커밋이 바뀝니다(그냥 은 옛 커밋을 남깁니다). B-rep 면 그물에는 (코어 0.7.1부터)를 둡니다(와이어프레임·숨은선에 삼각형 변 없이 B-rep 모서리만). 삼각형 형식(TESSELLATED 등)과 다각 고리(POLY_LOOP) 면이 든 그물은 모서리 선이 없어 삼각형 변을 그대로 그립니다. 개발 서버가 옛 코어를 미리 묶어 둔 채라면 로 다시 묶습니다. 첫 화면 JS를 줄이려고 코어 입구( — 뷰어·그리기·고르기)는 열기 상자를 열거나 파일을 끌어 오거나 문서를 열기 시작할 때 의 로 받습니다. 앱 입구에서 닿는 모듈은 코어의 작은 모듈(····· 등)만 값으로 가져오고 코어 입구는 타입으로만 가져옵니다 (가 앱 입구의 정적 가져오기 그래프를 훑어 확인합니다. 숫자 키 표 도 코어 0.10.0부터 작은 모듈에서 가져옵니다). 보기 링크의 고른 것 낱말()과 STL·OBJ·CSV 내보내기()도 첫 화면 JS에 넣지 않고 로 받습니다 — 문서를 열 때 미리 받아 두어 눌렀을 때 기다리지 않습니다(같은 시험이 확인). 그래서 몸체 줄·보기 링크 고른 것·간섭 안에 듦을 넣은 뒤에도 첫 화면 JS는 gzip 86.4 kB로 그 전(86.0 kB)과 거의 같습니다. 측정 곡선 접선 잠금()도 뷰어를 만들 때 의 로 받습니다(같은 시험이 확인 — 받기 전에는 곡선 끝에서도 코어 판정만). 곡선 접선 잠금과 정밀 조준 글상자 비키기를 넣은 뒤 첫 화면 JS는 gzip 86.1 kB에서 86.7 kB가 되었고, 접선 조각은 2.3 kB입니다. 곡선 가운데 접선 잠금은 곡선 계산(, NURBS 곡선 계산)과 함께 접선 조각에만 들어가 첫 화면 JS는 그대로(gzip 86.7 kB, 조각 이름만 바뀜)이고 접선 조각이 gzip 2.5 kB에서 6.8 kB가 되었습니다. 측정 붙잡기 다듬기와 곡선 길이 가운데 점()도 접선 조각에 넣어(코어에 을 주는 것은 조각을 받은 뒤 — 받기 전에는 꺾은선 위 점 그대로) 첫 화면 JS는 gzip 86.7 kB에서 87.0 kB(앱 연결·이름만), 접선 조각은 6.8 kB에서 9.6 kB가 되었습니다. 분해 계획과 분해 막대의 방식 단추·단계 글(·)도 문서를 열 때 로 받습니다(같은 시험이 확인 — 받기 전에는 막대 껍데기만 있고, 분해를 켜면 받은 뒤 겁니다). 조립 단계별 분해와 선 형상 몸체 줄을 넣은 뒤 첫 화면 JS는 gzip 86.98 kB에서 87.58 kB(막대 껍데기·보기 링크 ·선 형상 줄 — 분해 계산을 첫 화면에 두었을 때는 88.01 kB)가 되었고, 분해 조각은 1.6 kB입니다. 코어 0.15.0과 두 곡선의 교차점·원호 끝 매개변수를 넣은 뒤에도 첫 화면 JS는 gzip 87.59 kB 그대로(파일 크기도 같음)이고, 교차점 계산은 접선 조각에만 들어가 접선 조각이 gzip 9.56 kB에서 11.72 kB, 코어 조각이 64.54 kB에서 65.83 kB가 되었습니다. 코어 0.16.0·선분 식별자·끌어온 축과 B-스플라인 곡면 질량 속성을 넣은 뒤 첫 화면 JS는 gzip 87.43 kB에서 87.61 kB(물리 속성 도움말 글·끌어온 축 이름)이고, 접선 조각이 11.73 kB에서 12.47 kB, 코어 조각이 65.54 kB에서 67.15 kB, 해석 워커가 71.26 kB에서 76.40 kB(곡면 적분)가 되었습니다. 코어 0.17.0과 질량 속성 겉면 닫기(띠·꼭짓점 메우기)를 넣은 뒤 첫 화면 JS는 gzip 87.61 kB에서 87.90 kB(끌어온 축 이름 가르기)이고, 코어 조각이 67.15 kB에서 68.59 kB, 해석 워커가 76.40 kB에서 78.45 kB가 되었습니다(접선 조각은 12.46 kB 그대로). 코어 0.18.0과 첫 점 축과 모서리·면, 축 교차 다듬기를 넣은 뒤 첫 화면 JS는 gzip 87.90 kB에서 87.97 kB(축 위 점 이름 가르기)이고, 교차 계산은 접선 조각에만 들어가 접선 조각이 12.46 kB에서 13.12 kB, 코어 조각이 68.59 kB에서 69.97 kB가 되었습니다(해석 워커는 그대로). 코어 0.19.0과 잠근 선 교차, 축이 곡면을 뚫는 점 다듬기를 넣은 뒤 첫 화면 JS는 gzip 87.97 kB에서 88.52 kB(잠근 선 교차 이름·곡면 정의 요청)이고, 면 다듬기()는 접선 조각에 들어가 접선 조각이 13.12 kB에서 16.05 kB(NURBS 계산이 곡면 조각과 함께 쓰려고 이 조각으로 옮겨 옴), 곡면 정의 되살리기와 곡면 계산( — ·)은 접선 조각이 로 받는 곡면 조각(7.42 kB)에 들어갑니다. 코어 조각은 69.97 kB에서 70.53 kB, 해석 워커는 약 0.7 kB(곡면 정의 남기기·보내기) 늘었습니다. 코어 0.20.0과 극점 둘레 다시 풀기, 워커의 곡면 정의 격자 버리기를 넣은 뒤 첫 화면 JS는 gzip 88.65 kB 그대로입니다(첫 화면 모듈은 바뀌지 않았고, 0.19.0 때 88.52 kB에서 늘어난 몫은 그 뒤 올린 공용 사이트 도구의 계측). 접선 조각이 16.05 kB에서 16.55 kB(다시 풀기), 곡면 조각이 7.42 kB에서 7.49 kB, 코어 조각이 70.53 kB에서 71.84 kB(열린 교차) 늘었습니다. 거리 글상자 비키기와 접점 다듬기는 접선 조각에 들어가 첫 화면 JS는 gzip 88.65 kB에서 88.68 kB(조각 연결 몇 줄)이고, 접선 조각이 16.55 kB에서 17.23 kB가 되었습니다. B-스플라인 면 적분의 되짚기 다듬기는 해석 워커에 들어가 첫 화면 JS는 gzip 88.68 kB 그대로이고, 곡면 조각이 7.49 kB에서 7.54 kB(곡선의 점·도함수를 함께 구하기)가 되었습니다. 서비스 워커는 이 조각들도 미리 담아 오프라인에서 엽니다.

공용 사이트 도구: 다섯 언어 페이지·검색 정보·사이트맵·내용 수정일·언어별 앱 정보·서비스 워커 빌드, 공용 번역기, 언어 메뉴, 서비스 워커 등록·새 판 알림, 방문 통계, 휴대폰 성능 비교 명령은 다른 OpenCAD 앱과 함께 쓰는 opencad-site-kit (github:GyuTae-Kim/opencad-site-kit#v0.1.4, 잠금 커밋 a1de400, 빌드 때만 써서 devDependencies)에 있습니다. 이 앱에만 있는 값은 tools/site.mjs(앱 정보 원본, 서비스 워커 판 이름 짓기)와 tools/sw-source.mjs(서비스 워커 본문 — 돌려주는 글이 sw.js에 그대로 들어갑니다)에 둡니다. check:seo·check:i18n·test:seo·update:content-dates와 휴대폰 성능 예산 검사는 도구의 opencad-site 명령입니다. 도구 판을 올릴 때는 빌드 결과를 견줍니다.

npx vite build && cp -R dist .runtime/dist-before                                        # 올리기 전
npm install -D "opencad-site-kit@github:GyuTae-Kim/opencad-site-kit#<태그>"               # package.json·잠금 파일을 함께
npx vite build && npx opencad-site compare-dist .runtime/dist-before dist                 # 바뀐 파일과 처음 다른 곳

도구의 판 설명에 적힌 것 밖의 차이가 없으면, 스크립트가 바뀐 경우 내용 수정일을 갱신하고 빌드·시험을 돌립니다.

실제 파일 훑기

로컬에 있는 STEP 파일을 앱과 같은 해석 길(parseStepFile — 압축 풀기, STEP인지 가리기, stepToScene)로 모두 열어 보고 결과를 모읍니다. 표본 파일은 저장소에 넣지 않으므로 각자 가진 폴더를 줍니다.

npm run sweep -- --dirs ~/cad:~/Downloads --out .runtime/sweep/before        # 표본 폴더(쌍점으로 구분)
npm run sweep -- --dirs ~/cad:~/Downloads --out .runtime/sweep/after --quality normal,fine,finest
npm run sweep:compare -- .runtime/sweep/before .runtime/sweep/after           # 바뀐 파일만 보기

• 폴더를 재귀로 훑어 .stp .step .p21 .stpz .stp.gz와, 안에 STEP이 든 .gz .zip만 고릅니다. 내용(sha256)이 같은 파일은 한 번만 엽니다. 숨은 폴더와 node_modules는 건너뜁니다.
• --dirs가 없으면 환경 변수 OPENCAD_SWEEP_DIRS를 보고, 둘 다 없으면 쓰는 법만 보이고 끝납니다(CI에서는 돌지 않습니다). --list로 파일 목록을 줄 수도 있습니다.
• --quality에는 앱의 곡면 품질 이름(normal fine finest)이나 각도(20 10 5 — 최대 각만 바꿉니다)를 쉼표로 여러 개 줍니다. --jobs는 일꾼 수, --limit은 열 파일 수, --timeout은 파일 하나의 시간 한도(초)입니다.
• 앱처럼 질량 속성은 연 뒤 따로 적분합니다. 기록의 ms는 문서를 여는 시간(적분 빼고), propsMs는 그 뒤 적분 시간이고 요약에 둘 다 백분위로 남깁니다.
• 기록의 x에는 해석 워커가 화면으로 넘기는 양(이전하는 버퍼 바이트 합), 모서리 표와 그 가운데 곡선 정의의 바이트, 끝 접선을 아는 곡선 모서리 수와 그 가운데 곡선 정의로 접선을 구하는 수를 적고, 요약에 합·백분위·최대로 남깁니다. 로컬 표본 2,085개에서 곡선 정의는 모서리 표를 27.8 MiB에서 32.4 MiB로(+17%), 전송량 합을 222.2 MiB에서 226.8 MiB로(+2.1%, 파일마다 p90 +2.6%, 최대 +24%) 늘렸고, 곡선 모서리 117,673개가 모두 정의로 접선을 구했습니다(B-스플라인 한도를 넘는 것 없음). 정의를 만드는 시간은 곡선 정의가 가장 큰 30개 파일에서도 문서 여는 시간의 0.2% 안입니다. 원호·타원 호에 틀 x축과 두 끝 매개변수 각(수 다섯, 40바이트)을 더 실은 뒤에는 로컬 표본 1,864개에서 곡선 정의가 2.34 MiB에서 4.67 MiB, 모서리 표가 25.70 MiB에서 28.02 MiB(+9.0%), 전송량 합이 188.19 MiB에서 190.51 MiB(+1.2%, 파일마다 중앙 +1.1%, p90 +2.8%, 최대 +4.0%·94 KiB)가 되었습니다. 한 바퀴 원은 끝이 없어 싣지 않습니다(실으면 전송량 합 +2.1%). 분류·예외·품질 지표·질량 속성 지문은 하나도 바뀌지 않았습니다.
• 결과 폴더(기본 .runtime/sweep/<날짜-시각>)에는 records.jsonl과 summary.json이 생깁니다. records.jsonl은 파일과 품질마다 한 줄이고 열쇠는 내용 해시입니다 (경로는 이 로컬 결과에만 적습니다). summary.json에는 경로 없이 분류별 개수, 판(AP)별 개수, 오류와 경고 코드, 시간 백분위, 품질 지표를 적습니다. 결과가 이미 있으면 --resume(이어서)이나 --force(새로)를 줍니다. 비교 기준으로 남길 결과는 --keep으로 표시합니다.
• 품질 지표는 감기가 어긋난 입체, 부피가 음수인 입체, 접힌 삼각형(0.1% 넘는 파일 수와 가장 큰 개수 비율과 넓이 비율), 입체가 되지 못한 닫힌 껍질, B-rep 넓이와 크게 다른 면, 삼각형 합, 실패 면, 예외입니다. 닫힌 입체의 질량 속성(곡면 적분 정확·근삿값 섞임·삼각형으로 되돌림·시간 한도 수, 근삿값의 최대 어림 오차, 화면용 삼각형 부피와의 최대 차)과 값 지문(모든 입체의 질량 속성 float64 비트를 이은 FNV-1a 64비트)도 함께 적습니다. sweep:compare는 구한 길별 입체 수와 값 지문도 견줘, 해석기를 고친 뒤 질량 속성이 한 비트라도 바뀐 파일을 보입니다.
• sweep:compare는 같은 해시와 품질끼리 짝지어 분류가 바뀐 파일, 새 예외, 지표가 바뀐 파일(위 20개)과 요약 값을 전후로 보입니다. 출력에는 해시 앞 12자만 나옵니다(--paths를 주면 로컬 경로도). --fail-on-change를 주면 바뀐 것이 있을 때 1로 끝납니다.

휴대폰 검사

끌어오기 요청마다 .github/workflows/mobile-validation.yml이 PR 바탕(기준)과 PR(후보)을 같은 CI에서 빌드합니다. 휴대폰 첫 화면을 Lighthouse로 세 번씩 재서 중앙값 표를 작업 요약에 남깁니다(압축해서 주는 미리 보기 서버와 표는 공용 도구의 opencad-site serve-performance·performance-summary — 기준 빌드 뒤 이 커밋으로 돌아와 npm ci를 다시 해 명령을 찾습니다). 후보 중앙값이 tools/performance-budget.json의 예산을 넘으면 실패합니다(공용 도구의 opencad-site check-performance-budget). 지금 예산은 성능 90 이상, 접근성과 SEO 100, FCP 2초, LCP 2.2초, TBT 300ms, CLS 0.02, JS 88 KiB 이하입니다(코어를 나눠 받은 뒤 로컬 중앙값 82 KiB — 전에는 135 KiB). 예산을 바꿀 때는 그때 잰 중앙값을 같은 파일의 note에 적습니다.

이어서 playwright-cli로 휴대폰 화면(390×844, 손가락)에서 쓰는 흐름을 확인합니다(tools/mobile-browser-check.js, 판정은 tools/check-browser-result.mjs). 파일 고르기로 합성 표본(tools/mobile-sample.stp)을 열고, 최근 문서 다시 열기, 예제 열기, 두 번 눌러 거리 재기, 끌어다 놓기, ?open=과 ?sample, 없는 주소를 열 때의 알림까지 봅니다.

로컬에서는 npm run build 뒤 dist를 .runtime/performance/candidate(와 baseline)로 복사하고, Lighthouse와 playwright-cli를 npm install --prefix .runtime/mobile-audit --no-package-lock [email protected] @playwright/cli로 받아 워크플로의 "Compare cold mobile loads" 단계 명령을 그대로 돌립니다. 끝에 npx opencad-site check-performance-budget .runtime/performance로 예산을 봅니다.

배포

main에 push하면 .github/workflows/deploy.yml이 typecheck → test → build를 거쳐 dist/를 gh-pages 가지에 올립니다 (GitHub Pages: https://gyutae-kim.github.io/opencad-step/). 빌드는 상대 경로(base: './')라 어느 하위 경로에서도 돕니다. 끌어오기 요청은 .github/workflows/ci.yml이 같은 확인을 돌리고, .github/workflows/mobile-validation.yml이 휴대폰 검사(위 개발 절)를 돌립니다.

남은 일

• STEP-XML(.stpx, ISO 10303-28) 읽기
• PMI: 정의된 기호(DEFINED_SYMBOL), 파일이 정한 글꼴(TEXT_STYLE의 글꼴 이름)대로 그리기(지금은 내장 한 획 글꼴과 기기 기본 글꼴 윤곽선), 저장된 보기의 보이기 묶음·자르기 평면, 모서리·점에 이어진 PMI 강조, 큰 조립에서 같은 부품의 둘째 자리부터는 PMI를 다시 그리지 않음
• 경계가 없는 곡면(GEOMETRICALLY_BOUNDED_SURFACE_SHAPE_REPRESENTATION의 B-스플라인·잘린 곡면)을 그물로 그리기 (로컬 STEP 6,522개에 이 표현을 쓴 파일이 하나도 없어 실제 표본으로 확인할 수 있을 때로 미뤘습니다)
• 측정: B-스플라인 면·곡선끼리의 정확한 최소 거리(지금은 화면용 삼각형 ≈). 붙잡지 않은 면 위 점은 아직 삼각형 위이고(곡면 정의는 이제 화면에서 쓸 수 있지만 코어가 면 위 점을 다듬기로 넘기지 않음 — 코어에 그 손잡이가 생기면 같은 계산으로 옮길 수 있습니다), 곡선과 면의 교차점, 곡선 위 접점(첫 점에서 곡선에 그은 접선이 닿는 점)은 없습니다. 두 곡선의 교차점에서 곧은 모서리는 윤곽선 꼭짓점(float32)을 잇는 직선이라 그 정밀도를 따릅니다(곧은 모서리 정의는 모서리 표에 싣지 않음). 타원·B-스플라인이 낀 두 곡선이 접하는 자리(두 접선이 나란해 반복이 멈춤), 한 모서리의 자기 교차, 선 형상 곡선과의 교차는 다듬지 않아 꺾은선 교차점 그대로이거나 붙지 않습니다. 열린 후보(먼 수직 발·넓힌 교차점, 0.20.0의 축·잠근 선과 활꼴의 열린 교차)는 코어가 미리 보기 한 번에 앱 함수를 함께 6번까지만 새로 불러, 촘촘한 곡선이 여럿 겹친 자리에서는 몇 번 움직인 뒤에 붙습니다. 열린 교차는 확대해서 처짐이 반 화소보다 클 때만 붙고, 한 토막의 활꼴을 두 번 지나는 선은 코어 점에 가까운 하나만 받습니다. 축이 B-스플라인에 접하면서 아주 가까이 두 번 만나는 자리(두 교점 사이가 허용치 안)는 반복이 두 교점 사이에서 멈추면 그 사이 접선이 나란한 점에 찍힙니다(축에서 허용치 안). 개체 측정의 3D 덧그림 글상자(코어 setAnnotations)는 코어가 비켜 그리지 않아 휴대폰에서 측정 띠·뷰 큐브 밑에 들 수 있습니다(값은 측정 띠에 함께 보입니다 — 코어가 덧그림 글상자도 setMeasureLabelAvoid 자리를 비키게 되면 앱은 바꿀 것이 없습니다). B-스플라인 등의 곡면 정의는 두 점 측정을 켤 때 워커에서 받으므로, 받기 전에 코어가 물어 기억한 자리(같은 삼각형 위에 커서를 둔 동안)는 삼각형 위 점으로 남습니다. 다른 파일을 열다 실패하거나 취소하면 워커가 곡면 정의를 버려 앞 문서의 그런 면도 삼각형 위 점입니다. 질량 속성 적분이 도는 동안 워커는 곡면 정의를 되짚기 격자째 들고 있습니다. 격자를 버린 뒤 남는 몫은 곡면 정의 자체(조정점·매듭과 계산용 작은 버퍼)라, B-스플라인 면이 많은 작은 문서에서는 해석 결과의 절반쯤입니다(로컬 표본에서 가장 큰 것 55 kB). 띄운 곡면은 편도함수를 차분으로 구합니다(표본에는 없음)
• 고르기: 보기 링크는 표현 PMI 선만 따로 고른 것을 담지 못함(나무 자리 낱말이 없음 — 선 형상은 몸체 줄 낱말로 담김)
• 분해 보기: 부품을 끌어 옮겨 분해 단계를 손으로 만들고 저장하기, 한 축 방향으로만 벌리기(지금은 자리 가운데가 부모 가운데에서 멀어지는 쪽으로)
• 물리 속성: 로컬 표본(보통 품질)에서 근삿값이 남은 29개 입체(19개 파일) 가운데 24개는 모서리 곡선이 곡면에서 떨어진 거리로 잡은 관의 부피(모형의 허용 오차)가 부피의 1e-9를 넘는 것이고, 5개는 B-스플라인 면 몇 개를 곡면 적분의 어림 오차가 삼각형 쪽보다 커서 삼각형 + 띠로 잰 몫입니다(가장 큰 것 ±0.000011%). 오프셋 곡면은 아직 그 면만 삼각형이고(표본에는 없음), B-스플라인 면 적분은 모서리 곡선 위 가우스–크론로드 점마다 곡면에 되짚고(곡면 계산 3번쯤, 곡선이 곡면에서 떨어진 점은 2차 편도함수 한 번 더) 안쪽 적분을 해서, 매듭이 수백 개인 면이 있는 파일은 여전히 적분이 0.3초 넘게 걸립니다 (입체가 하나인 그런 파일은 시간 한도에 걸리지 않지만 느린 기기에서는 값이 늦게 나옵니다). 모서리 곡선이 곡면에서 되짚기 허용치보다 먼 면은 점마다 격자 짐작까지 해서 더 느립니다(표본에는 파일 하나). 다른 파일을 열기 시작하면 워커가 앞 문서의 적분 거리를 버리므로, 그 파일을 못 열거나 열기를 취소해 앞 문서가 남으면 적분이 덜 끝난 입체는 삼각형 값입니다 (그 파일을 다시 열지 않고 이어 하려면 새 해석이 끝날 때까지 앞 적분 거리를 들고 있어야 해 메모리를 더 씁니다)
• 간섭 검사: 겹친 부피, 열린 면 모형이 다른 입체 안에 든 경우
• 레이어: 면 단위 레이어 배정(지금은 형상 항목·껍질·첫 면까지 보고 형상 항목 하나를 한 레이어에 넣는다)

내력

2dcad-viewer의 src/formats/step/에서 분리했습니다(커밋 d7c584a 기준, 처음 들어온 것은 PR #7). 2D 뷰어 안에서 STEP 파일을 3D 탭으로 열던 화면(제품 나무 패널, 리본, 웹 워커 — src/app/view3d/)은 이 저장소의 혼자 도는 앱(src/app/)으로 새로 짰습니다(제품 나무·워커 프로토콜·이전 목록 등은 그 커밋의 코드를 옮겨 다듬었습니다).

라이선스

MIT. 의존성 earcut은 ISC입니다(THIRD_PARTY_NOTICES.md).

검색·공유 메타데이터와 콘텐츠 수정일

site/metadata.json을 공통 원본으로 삼아 Vite 플러그인이 제목·설명·canonical·Open Graph·Twitter Card·JSON-LD를 초기 HTML에 넣습니다. 같은 원본으로 앱의 공개 주소를 담은 sitemap.xml도 생성합니다. 공유 이미지는 각 앱의 public/og-opencad.jpg이며 앱 파일과 함께 배포합니다. robots.txt는 같은 호스트 루트(https://gyutae-kim.github.io/robots.txt)의 설정이 적용됩니다.

site/content-history.json에는 실제 콘텐츠 수정 시각과 지문을 저장합니다. 초기 HTML 본문·메타데이터·공유 이미지와 빌드된 앱/워커 JavaScript·CSS를 비교하므로 앱 기능이 바뀌면 날짜 갱신이 필요합니다. 수정일 자체와 소스 맵은 비교에서 제외합니다.

1. 콘텐츠를 변경한 실제 UTC 시각을 기록하고 npm run update:content-dates -- --at YYYY-MM-DDTHH:mm:ssZ를 실행합니다.
2. npm run build로 다시 빌드합니다. 변경되지 않은 콘텐츠는 기존 날짜를 유지하며, 날짜가 오래되었거나 잘못된 경우 SEO 검사가 실패해 배포를 막습니다.
3. npm run test:seo와 기존 테스트를 실행하고 메타데이터·수정일 기록을 함께 커밋합니다.

일반 빌드나 배포 시각으로 날짜를 자동 갱신하지 않습니다. sitemap.xml의 lastmod와 앱 구조화 데이터의 dateModified는 동일한 기록을 사용합니다. 배포 뒤에는 앱·사이트맵·공유 이미지의 실제 공개 응답을 확인하고, 포트폴리오 통합 사이트맵의 연결 날짜도 새 앱 사이트맵과 맞춥니다. 사이트맵 게시와 검색엔진의 실제 수집·색인 완료는 별도로 확인합니다.

다국어 UI와 정적 소개

한국어 기본 주소와 영어(/en/), 일본어(/ja/), 중국어 간체(/zh-CN/), 독일어(/de/) 페이지를 제공합니다. 각 언어의 소개 본문과 검색·공유 메타데이터를 빌드할 때 생성하며, hreflang과 사이트맵이 같은 페이지의 언어들을 연결합니다. site/locales/*.json에 한국어 원문과 번역을 저장하고, 브라우저는 선택한 언어의 사전만 내려받습니다. 방문 중 외부 번역 서비스는 호출하지 않습니다.

우측 상단 지구본 아이콘에서 언어를 선택합니다. 방향키로 이동하고 Escape나 바깥 클릭으로 닫을 수 있습니다. 언어 선택은 URL에 반영하며, 열린 문서나 편집 상태를 다시 만들지 않고 화면 문구·접근성 설명·오류·도움말을 갱신합니다. 명령 식별자·입력값·파일명·모델 이름·원본 도면의 문자는 번역하지 않습니다. 새 데이터 이름을 표시하는 요소에는 translate="no"를 지정하고, UI 문구의 {0} 같은 변수 자리를 변경하지 마세요. 여러 줄 메시지와 새 한국어 문구도 번역 사전에 추가해야 합니다. ·로 이은 문장은 짧은 변수 문구(예: 제품 번호 {0})가 뒤 조각까지 그대로 잡으면 조각마다 따로 옮깁니다(남는 한국어가 적은 쪽을 고름 — 잡은 이름은 여전히 그대로). 해석기 경고 안의 까닭 목록("삼각화하지 못한 면 3개 / 100개 (경계 고리 없음 2, 평면 삼각화 실패 1)")은 문장 틀의 자리 값이라 그대로 남으므로, 화면에서 까닭 조각을 따로 감싸 조각마다 사전으로 옮깁니다(src/app/warnparts.ts).

npm run test:i18n은 언어 전환과 문서 데이터 보존을, npm run check:i18n은 다섯 언어의 정적 소개·canonical·언어 링크·사전 변수·에셋 경로를 검사합니다. 번역이나 앱을 수정하면 기존 콘텐츠 수정일 갱신 절차를 따른 뒤 다시 빌드합니다. 자동 번역 초안의 주요 메뉴와 제품명은 교정했으며, 긴 기술 설명에는 추가 원어민 감수가 필요합니다.