From b0222089c627918eeac2034e4bde272814dcfdcf Mon Sep 17 00:00:00 2001 From: Antigravity Agent Date: Thu, 29 Oct 2026 14:33:49 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20=EB=8B=A8=EA=B3=84=EB=B3=84=20=EC=83=81?= =?UTF-8?q?=EC=84=B8=20=EA=B8=B0=EB=8A=A5=20=EB=B0=8F=20=EC=A1=B0=EC=9E=91?= =?UTF-8?q?=20=EA=B0=80=EC=9D=B4=EB=93=9C=EB=A1=9C=20README.md=20=EA=B0=9C?= =?UTF-8?q?=EC=A0=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 276 ++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 217 insertions(+), 59 deletions(-) diff --git a/README.md b/README.md index 5c37b51..1982b16 100644 --- a/README.md +++ b/README.md @@ -1,78 +1,236 @@ -# 2D 도면 기반 3D 수로암거 및 옹벽형 날개벽 모델링 웹 시스템 (Code/3d-drawing) +# 수로암거 및 날개벽 3D 외형·배근 통합 모델링 웹 시스템 (Wingwall 3D Modeler) -2D CAD 도면(일반도 및 구조도/배근도 DWG/DXF 5종)을 분석하여 수로암거(`STA.13+611.21`) 및 옹벽형 날개벽의 3D 솔리드 외형과 3D 내부 철근 배근(19종 508본)을 자동 구축하고, Three.js 기반의 웹 뷰어를 통해 인터랙티브하게 확인·검증·내보내기하는 시스템입니다. +> **2D 토목 CAD 도면(DWG/DXF)을 브라우저에 업로드하여 암거 본체 및 날개벽의 3D 외형 솔리드(Solid Mesh)와 내부 19종 철근(총 508본) 배근 모델을 3단계 자동화 공정으로 생성·검증·내보내기하는 웹 기반 CAD/BIM 엔지니어링 솔루션입니다.** --- -## 1. 주요 특징 및 구현 내용 - -- **1단계: 도면 불러오기 및 도면 종류 판별** - - DWG/DXF 파일 파싱 (`ezdwg`, `ezdxf`) - - 도면명 키워드 자동 판별: `'일반'` ➔ 일반도, `'배근'`/`'구조'` ➔ 구조도/배근도 - - 2D CAD 벡터 뷰어 및 레이어 제어 지원 -- **2단계: 일반도 기반 3D 외형 모델링** - - 암거 본체 및 날개벽 위치 판별 (시점부 좌/우, 종점부 좌/우) - - 본 도면 특성 완벽 준수: 시점부 미표기 ➔ 임의 생성 배제 / 종점부 좌·우 2개소 모델링 ($L=4.35\text{m}$, $L=5.40\text{m}$) - - 완전 폐합 2-Manifold 수밀성(Watertight) 3D 솔리드 메시 생성 (총 콘크리트 체적: $75.45\text{ m}^3$) -- **3단계: 배근도 기반 3D 철근 배근 모델링** - - 피복두께 80mm 준수 - - 19종 철근 기호, 총 508본 3D 입체 배근 (종점 좌 231본 + 종점 우 277본) - - 철근 재료표(BBS) 자동 산출 (총중량: $1.543\text{ TON}$, 할증 포함 $1.590\text{ TON}$) -- **웹 3D 뷰어 (Three.js)** - - 3차원 자유 시점 궤도 제어 (OrbitControls) - - 암거 본체 / 날개벽 / 철근 레이어별 가시화 및 투명도 제어 - - 3D 모델 OBJ, STL, DXF 내보내기 +## 📌 목차 +1. [프로젝트 개요](#1-프로젝트-개요) +2. [전체 시스템 파이프라인](#2-전체-시스템-파이프라인) +3. [단계별 상세 기능 및 동작 방법](#3-단계별-상세-기능-및-동작-방법) + - [1단계: 도면 불러오기 및 종류 판별](#1단계-도면-불러오기-및-종류-판별) + - [2단계: 일반도 기반 암거 및 날개벽 3D 외형 모델링](#2단계-일반도-기반-암거-및-날개벽-3d-외형-모델링) + - [3단계: 배근도 기반 날개벽 내부 3D 철근 배근](#3단계-배근도-기반-날개벽-내부-3d-철근-배근) + - [4단계: BIM 데이터 및 철근 가공조립표 내보내기](#4단계-bim-데이터-및-철근-가공조립표-내보내기) +4. [설치 및 실행 방법](#4-설치-및-실행-방법) +5. [프로젝트 디렉터리 구조](#5-프로젝트-디렉터리-구조) +6. [자동화 단위 및 파이프라인 검증](#6-자동화-단위-및-파이프라인-검증) --- -## 2. 작업 환경 및 디렉터리 구성 +## 1. 프로젝트 개요 -- **작업 환경**: WSL2 (Ubuntu Linux) -- **저장소 위치**: `Code/3d-drawing/` (Git 관리) +- **대상 구조물**: 대산당진 고속도로 수로암거 (`STA.13+611.21`, 내공 $B=2.0\text{ m}$, 사각 $\theta=105.879^\circ$) +- **입력 도면 5종**: + 1. `13. 수로암거 일반도(STA.13+611.21)(02).dwg` (일반도) + 2. `14. 수로암거 구조도(STA.13+611.21, 종점 우)(01).dwg` (종점 우측 배근도 1) + 3. `14. 수로암거 구조도(STA.13+611.21, 종점 우)(02).dwg` (종점 우측 배근도 2) + 4. `14. 수로암거 구조도(STA.13+611.21, 종점 좌)(03).dwg` (종점 좌측 배근도 1) + 5. `14. 수로암거 구조도(STA.13+611.21, 종점 좌)(04).dwg` (종점 좌측 배근도 2) +- **핵심 기술 스택**: + - **백엔드**: Python 3.10+, Flask, Flask-CORS, ezdwg, numpy + - **프론트엔드**: Three.js (WebGL 3D), HTML5 Canvas 2D 벡터 뷰어, Vanilla JavaScript, CSS3 + - **상호운용성**: OBJ, STL, AutoCAD 3D-DXF, CSV(Bar Bending Schedule) + +--- + +## 2. 전체 시스템 파이프라인 + +```mermaid +flowchart TD + subgraph Step1["1단계: 도면 불러오기 및 종류 판별"] + DWG["DWG/DXF 5종 업로드"] --> AutoClassify["키워드 기반 도면 자동 분류
(일반 / 배근·구조 / 미분류)"] + AutoClassify --> VectorViewer["2D CAD 벡터 뷰어 표출
(팬/줌/레이어 제어)"] + end + + subgraph Step2["2단계: 일반도 기반 3D 외형 모델링"] + VectorViewer --> CulvertExtract["평면도 점선 인식
암거 본체 기하 추출"] + CulvertExtract --> WingwallExtract["종점부 좌/우 날개벽 치수 보간
(A-A/B-B, C-C/D-D 단면)"] + WingwallExtract --> MeshGen["완전 폐합 수밀 솔리드 생성
(체적 75.45 m³)"] + end + + subgraph Step3["3단계: 구조도 기반 3D 철근 배근"] + MeshGen --> RebarExtract["재료표 & 단면 배근도 파싱"] + RebarExtract --> RebarGen["19종 철근 3D 공간 폴리라인 생성
(총 508본, 피복두께 80mm 준수)"] + RebarGen --> RebarBOM["철근 가공조립표 산출
(총연장 1,092.8m, 중량 1.543 TON)"] + end + + subgraph Step4["4단계: 3D 인터랙션 & 내보내기"] + RebarGen --> Interactive3D["Three.js 3D 뷰어 표출
(부재별 격리/거리비례 라벨)"] + Interactive3D --> Export["BIM 내보내기
(OBJ / STL / 3D DXF / CSV / JSON)"] + end +``` + +--- + +## 3. 단계별 상세 기능 및 동작 방법 + +### 1단계: 도면 불러오기 및 종류 판별 + +#### 1) 주요 기능 +- **다중 도면 업로드**: 여러 개의 `.dwg` 또는 `.dxf` 파일을 동시에 선택하거나 드래그 앤 드롭으로 업로드합니다. +- **키워드 자동 판별**: + - 도면명에 `'일반'` 포함 ➔ **일반도(`GENERAL`)**로 자동 분류 + - 도면명에 `'배근'` 또는 `'구조'` 포함 ➔ **배근도/구조도(`REBAR`)**로 자동 분류 + - 판별 키워드가 없을 경우 ➔ **미분류(`UNCLASSIFIED`)** 상태로 지정 +- **수동 분류 오버라이드**: 자동 판별 결과가 맞지 않거나 미분류된 경우, UI에서 즉시 '일반도' 또는 '배근도/구조도' 버튼을 클릭하여 수동으로 변경할 수 있습니다. +- **2D CAD 벡터 뷰어**: 업로드된 도면의 엔티티(선, 폴리라인, 텍스트, 원호 등)를 HTML5 Canvas 기반 벡터 뷰어에서 확인하고 레이어별 On/Off를 제어할 수 있습니다. + +#### 2) 화면 조작 방법 +1. 화면 상단의 **`[1단계: 도면 불러오기 및 판별]`** 탭을 클릭합니다. +2. 좌측 패널의 **`[도면 파일 선택]`** 버튼을 클릭하거나 점선 영역으로 DWG 파일들을 드래그합니다. +3. 목록에 표시된 각 도면의 **`[일반도]`** / **`[배근도/구조도]`** 배지를 확인하고, 필요 시 클릭하여 분류를 변경합니다. +4. 도면 항목을 클릭하면 우측 뷰어에 2D CAD 도면이 즉시 렌더링되며, 마우스 휠(확대/축소)과 드래그(이동)로 검토할 수 있습니다. + +--- + +### 2단계: 일반도 기반 암거 및 날개벽 3D 외형 모델링 + +#### 1) 주요 기능 +- **암거 본체 자동 인식**: 일반도 평면도 상단/하단 점선(`CS-CONC-MINR` 레이어, `A-DASHD01` 선형)을 감지하여 내공 스팬 $B=2.00\text{ m}$, 사각 $\theta=105.879^\circ$, 외폭 $3.40\text{ m}$, 높이 $H=2.60\text{ m}$를 자동 산출합니다. +- **날개벽 위치 및 단면 보간**: + - **시점부 날개벽**: 일반도 평면도 좌측 미표기 ➔ **규정에 따라 임의 생성 없이 모델링 제외** + - **종점부 좌측 날개벽 (`END_LEFT`)**: $L=4.350\text{ m}$, 설치각도 $134^\circ$, 단면 A-A(시점부) ↔ B-B(종점부) 선형 가변 보간 + - **종점부 우측 날개벽 (`END_RIGHT`)**: $L=5.400\text{ m}$, 설치각도 $151^\circ$, 단면 C-C(시점부) ↔ D-D(종점부) 선형 가변 보간 +- **수밀 솔리드 메시(Watertight Solid)**: 모든 면이 빈틈없이 닫힌 2-Manifold 솔리드로 생성되어 정확한 콘크리트 체적을 산출합니다: + - 암거 본체: $59.04\text{ m}^3$ + - 종점부 좌측 날개벽: $7.32\text{ m}^3$ + - 종점부 우측 날개벽: $9.09\text{ m}^3$ + - **총 콘크리트 체적**: **$75.45\text{ m}^3$** + +#### 2) 화면 조작 방법 +1. 상단 **`[2단계: 날개벽 외형 모델링]`** 탭을 클릭합니다. +2. 좌측 제어판에서 **날개벽 구성 모드**를 실시간으로 테스트할 수 있습니다: + - `종점부만 (도면 기준)` : 본 도면의 기본 상태 (종점 2개소 모델링) + - `양측 모두 (4개소)` : 시점·종점 4개 날개벽 시뮬레이션 + - `시점부만 (2개소)` / `날개벽 없음 (암거 본체 단독)` +3. 3D 뷰포트에서 마우스 조작: + - **좌클릭 드래그**: 3D 회전 (Orbit) + - **우클릭 드래그**: 화면 이동 (Pan) + - **마우스 휠**: 줌 인/아웃 (Zoom) +4. 3D 화면의 부재(암거 본체, 좌/우 날개벽)를 직접 클릭하면 해당 부재가 반투명 파란색으로 하이라이트되며 우측 하단에 상세 제원 카드가 표시됩니다. + +--- + +### 3단계: 배근도 기반 날개벽 내부 3D 철근 배근 + +#### 1) 주요 기능 +- **19종 철근 자동 3D 배치**: 4종 구조도의 철근 재료표와 상세도를 파싱하여 피복두께(80mm)를 유지한 상태로 날개벽 내부 공간에 3D 중심선 폴리라인을 생성합니다. +- **주요 철근 배근 내역 (총 508본)**: + - **우각부 사각 보강근 (`C1, C2`)**: 암거-날개벽 접합부 전면/배면 사각 절곡 정착근 (H19 @250, 각 13본) + - **벽체 수직 주철근 (`W1, W5, W6`)**: L형 기초정착 수직 주철근 (H16 @250, 1·2Cycle 교대 @125 배근) + - **벽체 수평 배력철근 (`W2~W4, W7~W9`)**: 하부 연속 배력근(4단), 상부 경사 가변 배력근(8단), 천단 연단근(H13 @250) + - **저판 횡방향 주철근 (`F1, F2, F6`)**: 양단 후크 가변 주철근 (H16 @250) + - **저판 종방향 배력철근 (`F3~F5, F7~F9`)**: 저판 폭 변화 맞춤형 배력근 (H13 @250) + - **헌치 및 전단 보강근 (`K1, K2, S1~S3`)**: 벽체-저판 접합부 헌치근 및 스터럽/타이바 +- **정밀 물량 집계**: + - 종점부 좌측 ($L=4.35\text{m}$): 231본, 총길이 485.111m, 중량 0.688 TON + - 종점부 우측 ($L=5.40\text{m}$): 277본, 총길이 607.664m, 중량 0.855 TON + - **합계**: **총 508본**, 총길이 **1,092.775m**, 총중량 **1.543 TON** (할증 3% 적용 시 **1.590 TON**) + +#### 2) 화면 조작 방법 +1. 상단 **`[3단계: 날개벽 철근 배근]`** 탭을 클릭합니다. +2. 좌측 사이드바에서 검토할 날개벽(`종점 좌측` 또는 `종점 우측`)을 선택합니다. +3. 하위 철근 기호 목록(`W1`, `C1`, `F1` 등)을 클릭하면: + - 선택한 철근군만 선명한 색상으로 **단독 격리(Isolate)**되어 표시됩니다. + - 다른 철근과 콘크리트 외형은 반투명 처리되어 내부 간섭 및 피복 상태를 직관적으로 확인할 수 있습니다. + - 카메라 거리에 비례하여 3D 텍스트 라벨 크기가 자동 보정되어 시인성이 유지됩니다. +4. 우측 상단 HUD 패널에서 규격(H13, H16, H19), 직경, 본당 길이, 수량, 총중량을 실시간 대조할 수 있습니다. + +--- + +### 4단계: BIM 데이터 및 철근 가공조립표 내보내기 + +상단 우측의 **`[내보내기]`** 드롭다운 메뉴를 통해 5가지 엔지니어링 포맷으로 즉시 다운로드할 수 있습니다: + +| 포맷 | 파일명 | 용도 및 호환 소프트웨어 | +| :--- | :--- | :--- | +| **OBJ** | `wingwall_model.obj` | 3D 형상 + 철근 폴리라인 메시 (Blender, 3ds Max, Rhino) | +| **STL** | `wingwall_model.stl` | 콘크리트 외형 수밀 솔리드 메시 (3D 프린팅, BIM 검증도구) | +| **DXF** | `wingwall_model_3d.dxf` | AutoCAD 3D Face(외형) + 3D Polyline(철근) 레이어 분리 파일 | +| **CSV** | `wingwall_rebar_bom.csv` | Excel 호환 철근 가공조립표 (BBS: 규격, 형상, 길이, 중량) | +| **JSON** | `model_3d.json` | 3D 정점 및 철근 좌표 원시 데이터 (API 연동용) | + +--- + +## 4. 설치 및 실행 방법 + +### 사전 요구사항 +- **Python**: 3.10 이상 권장 +- **운영체제**: Windows 10/11, macOS, Linux (WSL2 지원) +- **웹 브라우저**: Chrome, Edge, Firefox, Safari (WebGL 2.0 지원 브라우저) + +### 의존성 패키지 설치 +```bash +pip install -r requirements.txt +``` + +--- + +### 실행 모드 선택 (3가지 방식 지원) + +#### 방법 1. 로컬 Flask 웹 서버 실행 (권장) +- **Windows**: `run_server.bat` 더블클릭 또는 터미널에서 실행: + ```powershell + python app.py + ``` +- 서버 구동 후 브라우저에서 `http://127.0.0.1:5000/` 에 접속합니다. +- 동적 DWG 파일 업로드 및 실시간 파싱, 내보내기 API가 모두 활성화됩니다. + +#### 방법 2. 독립형 정적 브라우저 실행 (서버 불필요) +- [`index.html`](index.html) 파일을 웹 브라우저로 직접 더블클릭하여 엽니다. +- `static/data/`에 사전 번들링된 도면 및 3D 모델 데이터를 기반으로 서버 없이도 1단계~3단계 모든 3D 뷰어 기능이 오프라인에서 100% 작동합니다. + +#### 방법 3. Linux / WSL2 환경 실행 +- 제공된 쉘 스크립트를 실행합니다: + ```bash + bash run_wsl.sh + ``` + +--- + +## 5. 프로젝트 디렉터리 구조 ```text -Code/3d-drawing/ -├── cad_parser.py # 2D DWG/DXF 도면 파싱 및 종류 판별 -├── model_3d.py # 3D 수로암거 및 날개벽 파라메트릭 솔리드 모델러 -├── rebar_model.py # 3D 철근 배근 생성기 (19종 기호, 508본) -├── exporters.py # OBJ / STL / DXF 3D 파일 내보내기 모듈 -├── bundle_data.py # 도면 및 3D 데이터 번들링 유틸리티 -├── app.py # Flask 웹 REST API 서버 -├── index.html # Three.js 기반 3D CAD/BIM 웹 뷰어 -├── static/ # CSS, JS(app.js, viewer3d.js), Three.js 라이브러리 및 데이터 -├── run_wsl.sh # WSL2 원클릭 실행 스크립트 -├── test_pipeline.py # 파이프라인 전수 자동화 검증 테스트 -├── requirements.txt # Python 패키지 의존성 -└── README.md # 본 설명서 +├── app.py # Flask 백엔드 REST API 서버 +├── cad_parser.py # ezdwg 기반 DWG 파서 및 도면 자동 판별 엔진 +├── model_3d.py # 일반도 기반 3D 외형 솔리드 메시 생성 엔진 +├── rebar_model.py # 구조도 기반 19종 철근 3D 공간 배근 엔진 +├── exporters.py # OBJ, STL, 3D-DXF, CSV 파일 내보내기 변환기 +├── bundle_data.py # 정적 오프라인 구동용 데이터 번들러 +├── index.html # Three.js 3D 뷰어 단일 페이지 프론트엔드 (SPA) +├── requirements.txt # 필수 파이썬 패키지 목록 (flask, ezdwg 등) +├── test_pipeline.py # 1~3단계 전체 공정 E2E 통합 검증 테스트 +├── static/ +│ ├── css/ +│ │ └── style.css # 3단계 반응형 UI 레이아웃 스타일시트 +│ ├── js/ +│ │ ├── app.js # UI 이벤트 및 단계별 상태 관리 로직 +│ │ ├── viewer3d.js # Three.js 3D 씬, 조명, 카메라, 철근 격리 렌더러 +│ │ └── cad2d.js # 2D CAD 벡터 뷰어 캔버스 제어기 +│ ├── libs/ +│ │ ├── three.min.js # Three.js r128 코어 라이브러리 +│ │ └── OrbitControls.js # 카메라 마우스 궤도 제어기 +│ └── data/ +│ ├── drawing_data.js # 번들링된 도면 파싱 데이터 +│ └── model_3d.js # 번들링된 3D 외형 및 배근 데이터 +├── DOC/ +│ └── 04_실행/ # 버전별 개발 및 검증 보고서 (v0.1.00 ~ v0.1.10) +└── README.md # 본 시스템 명세서 ``` --- -## 3. 원클릭 실행 방법 +## 6. 자동화 단위 및 파이프라인 검증 -### 3.1. Windows 환경 (권장) -최상위 폴더 또는 `Code/3d-drawing/` 내의 실행 파일을 더블클릭합니다: -- **`[실행]_암거및날개벽_3D외형배근모델러.bat`**: 백엔드 서버(WSL2 또는 Windows Python) 자동 기동 및 웹 브라우저(`http://localhost:5000`) 자동 오픈 -- **`[실행바로가기]_암거및날개벽_3D외형배근모델러.lnk`**: 윈도우 바로가기 아이콘 -- **`[바로가기]_3D모델러_웹접속.url`**: 서버 동작 중 브라우저 즉시 열기 - -### 3.2. WSL2(Ubuntu) 터미널 환경 -WSL2(Ubuntu) 터미널에서 아래 명령을 실행합니다: +프로젝트 루트에서 다음 명령을 실행하여 도면 파싱, 외형 수밀성, 19종 철근 508본 배근, 내보내기 API의 정상 동작을 한 번에 검증할 수 있습니다: ```bash -cd Code/3d-drawing -chmod +x run_wsl.sh -./run_wsl.sh +python test_pipeline.py ``` -실행 후 웹 브라우저에서 아래 주소로 접속합니다: -- **`http://localhost:5000`** 또는 **`http://127.0.0.1:5000`** - ---- - -## 4. 자동 테스트 및 검증 실행 - -```bash -cd Code/3d-drawing -~/.venv-3d-drawing/bin/python test_pipeline.py -``` +### 주요 검증 단정문 (Assertions) +- **도면 판별**: `classify_drawing_by_name()`의 `'일반'` ➔ `GENERAL`, `'구조'` ➔ `REBAR` 일치 검증 +- **수밀성 검사**: 날개벽 솔리드 메시의 Open Boundary Edge = 0, Non-manifold Edge = 0 검증 +- **철근 제원 일치**: 종점 좌(231본) + 종점 우(277본) = 총 508본, 총길이 1,092.775m, 중량 1.543 TON 일치 검증 +- **내보내기 무결성**: OBJ, STL, DXF, CSV, JSON 응답 크기 및 데이터 정합성 검증