Tunnel3D/docs/VERIFICATION_PLAN.md

터널 단면 2D/3D 자동 모델러 검증계획서 (Verification & Validation Plan)

프로젝트명: 도로·철도 터널 표준단면 2D DXF 자동 해석 및 3D 파라메트릭 모델러 (TunnelModeler3D)
문서 버전: v1.0
작성일: 2026-10-29
개발/검증 책임: m12205.tdc.hanmacgroup@gmail.com
대상 리포지토리: hylee4/Tunnel3D

---

1. 개요 및 목적

1.1 목적

본 검증계획서는 실무 터널 설계도면(AutoCAD DWG/DXF)을 입력받아 터널 라이닝, 도로 포장, 공동구, 배수시설 등 복합 기하 요소를 자동으로 추출하고 3D 모델로 변환하는 TunnelModeler3D 프로그램의 기하학적 정밀도, 오작도 보정 성능, 실무 범용성 및 형상 무결성을 객관적으로 입증하기 위해 수립되었습니다.

1.2 검증 대상 핵심 모듈

• app.js: DXF 파싱, 기하 추론 엔진, 공동구 트렌치 추적, 2D/3D 렌더링
• server.js: DWG/DXF 변환 및 로컬 서빙
• index.html & style.css: 사용자 인터페이스 및 개발자 저작권 크레딧 표시

---

2. 검증 범위 및 주요 검증 항목

flowchart LR
    A["입력: CAD 도면 (DWG/DXF)"] --> B["1. 파싱 & 기하 추출"]
    B --> C["2. 오작도 & 예외 보정"]
    C --> D["3. 2D/3D 루프 생성"]
    D --> E["4. 실무 도면 회귀 검증"]
    E --> F["최종 성과품 (OBJ/3DM/데이터)"]

2.1 터널 라이닝 원호 체계 (R_1 \sim R_5)

• R_1 (천단 원호): 반경 및 중심좌표 추출 정확도 (\pm 1\,\text{mm} 이내)
• R_2, R_3 (내공 좌·우측 원호): 접점 연속성 (G^1 연속성) 및 각도 기반 탐색 신뢰성
• R_4, R_5 (외공 좌·우측 원호): 숏크리트 및 라이닝 두께 연동 무결성

2.2 도로 포장 및 차로 시스템

• 포장 폭 정밀도: 설계 규격(11.3\,\text{m} 등)과 캐드 작도 오차(11.25\,\text{m}) 분리 보정 검증
• 차로 폭 및 측대 자동 산출: 차선 마커 인식 체인 및 좌우 측대 균등/설계 분할 검증
• 편경사(Cross Slope): 중심 능선 기준 좌우 기울기 정밀도

2.3 공동구 (Utility Duct) 및 뚜껑 (Precast Lid)

• 프리캐스트 뚜껑 자동 탐색: 두께 (40 \sim 120\,\text{mm}), 폭 (300 \sim 1,500\,\text{mm}) 박스 분리 검출
• 트렌치 내공 다각형 추적 (traceTrenchPoly):
  • Type-1: 직사각형 표준 단면
  • Type-2: 하부 경사 단면 (상단폭 대비 바닥폭 축소형)
  • Type-3: 특수 대형 단면 (모따기 챔퍼 130 \times 545\,\text{mm} 등 다각 루프)

2.4 배수 시설 (Ditch, 배수콘크리트, 집수정, 유공관)

• 배수홈(Ditch): 바닥 수평선(폭 100\,\text{mm}) 및 양단 수직벽(좌 148\,\text{mm} / 우 150\,\text{mm}) 독립 검출
• 배수콘크리트: 포장단부 하부 두께(좌 530\,\text{mm}, 우 500\,\text{mm}) 및 바닥폭(550\,\text{mm}) 정합성
• 종배수관(유공관): 상하부 중복 원(Circle) 중 메인 레벨(\varnothing 300\,\text{mm}) 선별 구속

---

3. 검증 환경 및 테스트 데이터셋

3.1 표준 테스트 벤치마크 도면군

No.	노선 및 터널명	차로수	단면 특성	주요 검증 포인트
TC-01	안성-구리 11공구 (남한산성터널)	3차로	대단면 본선터널	표층 11.25\,\text{m} 오작도 \to 11.3\,\text{m} 보정, 좌 T2 / 우 T3, Ditch 100 \times 150, 배수콘 530 / 500
TC-02	안성-구리 13공구 (방아다리터널)	3차로	대단면 도심지 터널	좌 T2(500\times640) / 우 T3(770\times940), 유공관 \varnothing 300, 절대좌표계 오프셋
TC-03	익산-대야 (완산터널)	2차로	철도/도로 표준형	2차로 포장폭(9.19\,\text{m}), 좌 T2 / 우 T3 규격
TC-04	천안-논산 (풍세터널)	2차로	표준 국도 단면	배수콘크리트 체인 추적 및 유공관 자동 매칭
TC-05	대산당진 / 광주강진	가변	소단면 및 갱구부	다양한 레이어 명칭(CS-CONC, CONC, 0 등) 적응성

---

4. 단계별 검증 절차 (Verification Procedures)

sequenceDiagram
    participant Tester as 검증자/자동화 스크립트
    participant Engine as 모델러 엔진 (app.js)
    participant Viewer as 2D/3D 뷰포트
    participant Gitea as Gitea 원격 저장소

    Tester->>Engine: 1. 테스트 도면(DXF) 로드
    Engine->>Engine: 2. 원호/선분 필터링 및 파라미터 자동 추출
    Engine->>Viewer: 3. 단면 제원 UI 동기화 및 2D 캔버스 렌더링
    Engine->>Viewer: 4. 3D 솔리드/Extrude 메쉬 생성 (Earcut)
    Tester->>Viewer: 5. 실측 CAD 치수와 일치 여부 판정 (오차 0mm)
    Tester->>Gitea: 6. 검증 완료 소스 및 리포트 커밋/푸시

4.1 단계 1: 단위 알고리즘 자동화 검증 (Automated Script Test)

• 방법: Headless Node.js 환경에서 자동화 검증 스크립트 실행
• 검증 기준:
  • 남한산성터널 포장폭: 정확히 11,300\,\text{mm} 산출 여부
  • 좌측 Ditch: dw=100\,\text{mm}, dh=150\,\text{mm}, bcw=550\,\text{mm}
  • 배수콘크리트 두께: 좌 530\,\text{mm}, 우 500\,\text{mm}
  • 우측 공동구 바닥폭 640\,\text{mm}, 하부 챔퍼 130 \times 545\,\text{mm} 반영 여부

4.2 단계 2: 기하 형상 솔리드 폐합 검증 (Watertight Solid Check)

• 방법: Rhino 3DM 및 Wavefront OBJ 내보내기 파일 검사
• 검증 기준:
  • lid_L, lid_R 프리캐스트 뚜껑의 3차원 루프 정상 생성 여부
  • 라이닝 링과 바닥 슬래브 간 자기교차(Self-intersection) 및 틈새(Gap) 0.01\,\text{mm} 이하 검증

4.3 단계 3: UI 렌더링 및 저작권 무결성 검증 (UI/Visual Acceptance)

• 방법: 브라우저 실행 후 2D/3D 캔버스 뷰 육안 검사
• 검증 기준:
  • 뷰포트 우측 하단 및 하단 상태바에 크레딧 표시: Developed by m12205.tdc.hanmacgroup@gmail.com · © 2026
  • 2D 캔버스 내보내기 시 좌측 하단 워터마크 자동 인자 확인

---

5. 허용 오차 기준 및 판정표 (Acceptance Criteria)

검증 항목	설계 기준값 (남한산성)	허용 오차	실제 측정값	판정
포장 전체 폭	11,300\,\text{mm}	\pm 0\,\text{mm}	11,300\,\text{mm}	PASS
차로 구성	3,600 \times 3\,\text{mm}	\pm 0\,\text{mm}	3,600+3,600+3,600\,\text{mm}	PASS
좌 / 우 측대폭	250\,\text{mm} / 250\,\text{mm}	\pm 0\,\text{mm}	250\,\text{mm} / 250\,\text{mm}	PASS
좌측 Ditch 규격	폭 100, 깊이 148/150	\pm 1\,\text{mm}	폭 100, 깊이 150\,\text{mm}	PASS
우측 배수콘 폭	550\,\text{mm}	\pm 1\,\text{mm}	550\,\text{mm}	PASS
배수콘 두께 (좌/우)	530\,\text{mm} / 500\,\text{mm}	\pm 1\,\text{mm}	530\,\text{mm} / 500\,\text{mm}	PASS
좌측 공동구 내공	500 \times 640 (바닥 450)	\pm 1\,\text{mm}	500 \times 640 (바닥 450)	PASS
우측 공동구 내공	770 \times 940 (바닥 640)	\pm 1\,\text{mm}	770 \times 940 (바닥 640)	PASS
종배수관 직경	\varnothing 300\,\text{mm}	\pm 0\,\text{mm}	\varnothing 300\,\text{mm}	PASS

---

6. 향후 일정 및 검증 보고 산출물

1. 테스트 자동화 CI 스크립트화:
   • 도면 파일 추가 시 verify_all.js를 통해 모든 터널 단면 자동 회귀 테스트 수행
2. 검증 보고서(Validation Report) Gitea 등록:
   • 검증 결과를 마크다운 및 PDF 보고서로 변환하여 원격 저장소(hylee4/Tunnel3D)의 Release/Docs로 관리
3. 설계 변경 이력 추적:
   • Gitea MCP Issue 도구를 활용하여 각 터널별 검증 이슈 생성 및 이력 영구 보존