bridge-drawing-extractor
Python으로 다른 프로그램에 연결하는 오프라인 교각 도면 추출 라이브러리입니다. GUI·AI API·네트워크 연결 없이 폴더의 DWG를 읽고 Pier/IP/Bearing 엑셀, 근거 JSON, 검토 CSV를 만듭니다.
패키지 버전: 0.1.5 (프로그램 v0.1.05).
설치
Python 3.10 이상이 필요합니다. Windows/Python 3.12에서 실행 검증했습니다.
python -m pip install --upgrade bridge_drawing_extractor-0.1.5-py3-none-any.whl
Python 의존성은 openpyxl>=3.1,<4입니다. 인터넷 없는 PC는 openpyxl과 그 의존성 et-xmlfile도 미리 설치하거나 설치 파일을 함께 준비하세요. 의존성이 이미 설치되었다면 --no-index --no-deps 옵션으로 wheel만 설치할 수 있습니다.
DWG 변환기는 LibreDWG dwgread를 별도로 준비합니다. 이 패키지는 변환기를 내려받거나 포함하지 않습니다. 탐색 우선순위:
- API의
converter_path/ CLI의--converter - 환경변수
BRIDGE_DWGREAD - 실행 환경의
PATH에서dwgread또는dwgread.exe
명시한 경로가 틀리면 다른 변환기로 조용히 대체하지 않고 오류를 반환합니다. 현재 작업 PC에서는 기존 Code/giyang_extract/libredwg/dwgread.exe를 사용할 수 있습니다. 다른 프로그램/PC에서는 해당 경로를 호스트 프로그램의 설정값으로 전달하세요. 패키지 실행에 이 프로젝트 폴더는 필요하지 않습니다.
Python API
from bridge_drawing_extractor import extract_folder, ExtractionError
try:
result = extract_folder(
r"D:\drawings\bridge_a",
output_dir=r"D:\results",
converter_path=r"C:\tools\libredwg\dwgread.exe",
on_progress=lambda message: print(message),
)
except ExtractionError as error:
print(f"추출 실패: {error}")
else:
print(result.status) # completed 또는 needs_review
for workbook in result.workbooks:
print(workbook.xlsx_path)
pier_cells = workbook.data["cells"]["Pier"]
bearing_cells = workbook.data["cells"]["Bearing"]
review_records = [
row for row in workbook.data["records"]
if row["status"] not in ("추출", "식별자", "등록값")
]
response = result.to_dict() # JSON 직렬화 가능한 dict, Path는 문자열로 변환
extract_folder(folder, *, output_dir=None, converter_path=None, on_progress=None)는 동기 함수입니다. GUI나 비동기 웹 서버에서는 작업 스레드/프로세스에서 호출하세요. 콜백에는 진행 메시지 문자열이 전달됩니다. 함수가 GUI 창이나 서버를 열지 않습니다.
출력 경로를 생략하면 입력 폴더의 _도면추출결과에 실행별 폴더를 만듭니다. 쓰기 권한이 필요합니다. 원본 DWG와 기존 결과는 수정하지 않습니다.
환경 확인:
from bridge_drawing_extractor import check_environment
print(check_environment(converter_path=r"C:\tools\libredwg\dwgread.exe"))
반환 형식
ExtractionResult:
schema_version: 현재"1.0". 패키지 버전과 별도인 결과 규약 버전.output_dir: 생성된 실행 폴더의Path.workbooks:WorkbookResult튜플.files: 입력 파일별 역할·상태·실패 사유 목록.review_count,failed_file_count: 검토 셀 및 읽기 실패 파일 수.status: 검토 항목이나 읽기 실패가 있으면needs_review, 없으면completed.to_dict(include_data=True): JSON 직렬화 가능.False는 큰 원문 데이터를 제외한 요약.
WorkbookResult: name, xlsx_path, json_path, review_csv_path, review_count, data.
data["cells"]는 시트별 Excel 셀 주소와 값의 매핑입니다. data["records"]에는 sheet, cell, value, status, messages, note, evidence가 있습니다. 각 행의 B열이 교각명이며, IP/Bearing의 C열은 지시점/받침번호입니다. 값은 숫자·문자·null이며 미확정 숫자는 0으로 대체하지 않습니다. 상충값은 messages/evidence에 보존합니다.
실행 성공은 설계값 확정을 뜻하지 않습니다. 파일 일부 읽기 실패가 있어도 결과를 만들 수 있으면 반환되므로 반드시 status와 files를 확인하세요. 치명 오류는 ExtractionError로 전달하며 기존 파일은 보존됩니다. 프로그래밍 오류는 예상치 못한 예외로 전파될 수 있습니다.
Python이 아닌 프로그램에서 호출
bridge-extract "D:\drawings" --output "D:\results" --converter "C:\tools\dwgread.exe"
python -m bridge_drawing_extractor "D:\drawings" --converter "C:\tools\dwgread.exe"
python -m bridge_drawing_extractor --check --converter "C:\tools\dwgread.exe"
- stdout: JSON 결과 한 건.
--include-data를 추가하면 셀·근거 데이터 포함. - stderr: 진행 로그. 한글 포함 UTF-8로 처리하세요.
- 종료 코드 0: 결과 생성 완료. JSON의
needs_review는 별도 확인 필요. - 종료 코드 1: 추출 실패, stdout의
status="error"와error확인. - 종료 코드 2: 잘못된 CLI 인자 또는
--check에서 변환기 미발견.
따라서 C#·Java·다른 Python 프로세스에서도 stdout JSON과 종료 코드로 연결할 수 있습니다. HTTP 서버·인증·작업 큐는 호스트 프로그램에서 관리합니다.
지원 범위
파일명은 판독 조건으로 사용하지 않습니다. 폴더 내 DWG를 먼저 열고 내부 제목·표 머리글·교각 번호·EL 표기를 읽어 종평면, 교각, 받침배치, ELEVATION 산출근거 역할을 판단합니다. 내부 제목도 교각도/교각구조도/교각일반도, 종단면도/종평면도 등 변형을 허용하며, 제목이 없어도 알려진 표 구조를 검사합니다. 식별 못한 파일은 files 및 파일판독내역 JSON에 역할 미확정으로 기록합니다.
| 추출 항목 | 적용 출처 |
|---|---|
| 교각형식 | 기본 T형 (사용자 지정) |
| 두부보 EL | ELEVATION 산출근거표의 교각별 교좌면 EL 최솟값 |
| 두부보 폭 | 교각별 모든 받침 X·Y의 최대 평면거리보다 큰 다음 500mm 단위 |
| 두부보 길이 | IP1-IP3 평면거리보다 큰 다음 500mm 단위 |
| 기초하단 EL, 지반고 EL, 기초형식, 말뚝길이 | 종평면도 역할 |
| IP 좌표 | 받침배치도 역할 |
| 받침 X·Y·방위각 | 받침배치도 역할 |
| 받침 Z | ELEVATION 산출근거표의 교량받침 EL(몰탈상단) |
| 기둥 개수 | T형 1개, π형 2개 (기본형식은 T형 유지) |
| 말뚝길이 | 종평면도의 길이/범위 중 최솟값, mm 단위 |
| 받침 전열/후열 | 받침배치도 표제의 전·후열과 교각/받침번호 연결 |
0.1.5부터 Pier H열은 m 대신 mm입니다. 예: 7~12m → 7000mm. Bearing H열에 전열/후열을 추가했으며 기존 방위각 G열은 유지합니다. 기존 연동 프로그램이 H열 길이를 m로 간주하거나 받침 열 수를 고정했다면 수정해야 합니다. 전후열 표기가 없거나 충돌하면 임의로 판단하지 않고 미확인/미확정으로 둡니다.
0.1.4부터 교각일반도는 사용하지 않습니다. ELEVATION 표의 교각명·받침번호·몰탈상단·교좌면 열을 연결합니다. 받침배치도에 방향 표기가 있으면 같은 방향의 표만 사용합니다. 동일 받침의 여러 표 값이 충돌하면 미확정으로 남깁니다. 필요한 표고가 없을 때 과거 교각일반도 값으로 대체하지 않습니다. 기둥 개수는 T형 1개, π형 2개로 입력합니다.
거리 단위는 좌표 m를 mm로 변환합니다. 6,200mm → 6,500mm, 정확히 6,500mm → 7,000mm입니다. 폭은 모든 받침 쌍의 유클리드 거리 최댓값이며, 길이는 IP1-IP3 직선거리입니다. 좌표 누락·상충이나 IP 번호 미확정이면 해당 치수를 비웁니다. T형은 기본값, 치수와 최소 표고는 산정값으로 엑셀 주석·검토 CSV에 구분합니다.
ELEVATION 원문은 data["supplementary_drawings"]에 보존하고 data["source_policy"]에 항목별 출처 규약을 제공합니다. 알 수 없는 표 구조까지 자동 해석한다는 뜻은 아닙니다.
DWG 문자 내용으로 파일 역할을 분류하고 좌표표 헤더·교각 번호·상대 배치를 판독합니다. 기존 산외교/기양천교의 배치 자료가 패키지에 포함됩니다. 새 명시형 제원표는 헤더로 읽습니다.
모든 설계사 도면의 자유 형상, OCR, 회전/비균일 변형, 블록 좌표 변환을 자동 해석하는 범용 도구는 아닙니다. 판독 근거가 모호한 항목은 공란과 검토 사유로 남깁니다. 입력 폴더에 여러 교량/개정본이 섞여 있으면 분리된 교량 폴더를 권장합니다. 기존 탐색 제외 폴더(backup, temp, outputs, Code, RAG, 숨김 폴더 등) 규칙을 유지합니다.
개발·빌드
python -m pip install .
python -m build
네트워크 없이 이미 설치된 setuptools/wheel만 사용하는 개발 환경에서는 python setup.py sdist bdist_wheel도 가능합니다. 결과는 dist/에 생성됩니다.
tools/import_engine.py는 최초 이관 스크립트이며 실행 의존성이 아닙니다. 이관 완료 후의 실행 정본은 src/bridge_drawing_extractor/입니다. 종전 데스크톱 앱은 별도로 보존되어 있으며 자동 동기화하지 않습니다.
변경 이력
| 버전 | 날짜 | 내용 |
|---|---|---|
| 0.1.5 | 2026-10-29 | T/π형 기둥 수, 말뚝길이 최소 mm, 방위각 옆 전열/후열 열 |
| 0.1.4 | 2026-10-28 | 교각일반도 제외, 기본 T형, 좌표 기반 500mm 치수, ELEVATION 몰탈상단 Z·교좌면 최소 EL |
| 0.1.3 | 2026-10-28 | 내부 도면명 변형 및 표 구조 분류 확장, ELEVATION 근거 원문 포함, 받침 Z 출처 분리 |
| 0.1.2 | 2026-10-28 | GUI 없는 import API, JSON CLI, 상대 모듈 import, 내장 배치 데이터, 외부 변환기 설정, wheel/sdist |
0.1.6 — 도면 폴더 입력 통합 (2026-10-29)
기존 엑셀 없이 extract_folder() 또는 도면추출 실행 바로가기로 DWG 폴더를 처리합니다. 파일명 대신 내부 문자로 종평면/받침배치/ELEVATION 역할을 분류합니다. 단독 표와 좌표·표고 통합표를 읽고, 받침 좌표 범위에 유일하게 대응하는 IP 3점을 위→아래로 정렬합니다. 교각 형식의 명시적 표기가 없으면 T형/1기둥을 기본값으로 표시합니다.
종평면의 표 데이터 또는 교각 주변 EL·지반고·기초·L 표기를 연결합니다. 인접 문자 추정값에는 지시선 검토 필요 표시가 붙습니다. 여러 방향/개정 도면의 동일 번호 값이 다르면 상충으로 남깁니다. 이미지형 PDF/OCR, 임의 형상의 기둥 개수 인식, 모든 종단 지반고 표의 측점 보간은 지원하지 않습니다. 이 경우 빈칸과 근거를 반환하며 완전 자동 확정을 보장하지 않습니다.
GUI: 폴더 선택 → 자동 추출 시작 → 결과 폴더 열기. 결과는 선택 폴더의 _도면추출결과 아래 실행 시각별 XLSX/JSON/CSV로 저장합니다. 외부 API/토큰/네트워크 호출은 없습니다. 외부 연동 API는 기존과 동일합니다. 이번 배치의 사람이 판독한 12개 결과는 별도로 유지되며 일반 추출 결과와 동일하지 않을 수 있습니다.
검증: 단위/회귀 16개, 실제 파일명을 바꾼 DWG-only 폴더(등록 레이아웃 비활성) 2교각·28받침·IP6점 추출, GUI 작업 스레드/출력 완료 시험. 재현 스크립트는 tests/test_folder_inference.py, tests/folder_only_smoke.py, tests/desktop_smoke.py에 있습니다.
0.1.7 — 두부보 폭 규칙 변경
두부보 폭 = ceil((전열·후열 받침 좌표 평균점 사이 거리_mm + 2000) / 500) × 500. 합계가 정확히 500mm 배수이면 그대로 유지합니다(예: 1500+2000=3500mm). 두 열 구분 또는 좌표가 부족하면 미확정 처리합니다. 두부보 길이 규칙은 유지합니다. 기존 12개 결과의 폭만 재계산한 사본은 추출결과_12개교량_20261029/두부보폭_전후열거리_2m반영 폴더에 있습니다.
0.1.8 — 블록·표선·지시선 기반 판독 보강
DWG의 모델/배치 공간 및 중첩 INSERT를 이동·회전·축척·기준점으로 전개합니다. 미삽입 블록 정의의 문자를 본도면 문자로 읽지 않습니다. LINE/LWPOLYLINE/LEADER 선분을 보관하고 표의 실제 가로선으로 행을 대응하며, 단순한 EL/GL 지시선은 연결된 끝점을 사용합니다. 블록 전개가 불가능한 경우 변환 경고를 남깁니다. 구버전 캐시는 자동 재생성합니다.
IP 검색은 받침 외곽 밖의 지시점까지 허용하되, 경쟁 교각·중복 후보·3점 불충족은 미확정으로 유지합니다. 종평면 말뚝 표기는 국부 기초 EL이 확인되는 영역에 한정하여 평면도 교각 번호와 다른 기초가 연결되는 것을 줄였습니다.
일반 형상으로 기둥 개수를 세거나, 모든 복잡한 지시선을 해석하거나, 스캔 PDF에 OCR을 수행하는 기능은 이번 버전에 포함하지 않았습니다. 양방향 번호 중복·개정 도면 상충도 자동 확정하지 않습니다. 12개 도면 비교의 수치 차이와 미확정을 통과로 처리하지 않으며 geometry_comparison 보고서에 보존합니다.