hwacheon-network-viewer/README.md

화천군 관망도

SWMM 입력 자료의 화천군 맨홀·우수관로를 WebGL로 탐색하는 웹사이트입니다. 검색, 시설 제원, 연결부 내부 보기, 레이어·배율·시점 조작을 제공합니다. 수리 해석은 수행하지 않습니다.

실행

Python 3.10 이상과 WebGL을 지원하는 최신 Chrome 또는 Edge가 필요합니다. Python 표준 라이브러리만 사용하며 별도 패키지 설치나 빌드가 없습니다.

cd /home/user/hwacheon-network-viewer
python3 start.py --port 8081

위 명령을 이 프로젝트 폴더에서 실행한 뒤, 터미널에 표시된 주소로 접속하세요. 위 예제의 주소는 http://127.0.0.1:8081/ 이며 화천 관망도 화면이 표시됩니다. 주소를 여는 것만으로 서버가 실행되지는 않습니다. 다른 위치에 복사했다면 해당 프로젝트 폴더에서 실행하세요.

이 예제는 다른 서버와의 포트 충돌을 피하기 위해 8081을 사용합니다. --port를 생략하면 기본 포트는 8080입니다. 해당 주소에 다른 화면이 보이면 이미 그 포트에서 다른 서버가 실행 중일 수 있으므로, 이 프로젝트의 실행 결과와 포트 번호를 확인하세요. 실행 터미널을 유지하고 종료할 때 Ctrl+C를 누릅니다.

내부망 공유는 python3 start.py --lan --port 8081로 실행합니다. WSL 환경에서는 Windows 포트 전달·방화벽 설정이 별도로 필요합니다. 공유 모드에는 로그인이 없습니다. 글꼴·스크립트·데이터는 모두 프로젝트 안에서 읽습니다.

파일 구성

• start.py, serve.py: 실행 진입점과 web/ 전용 HTTP 서버.
• web/index.html, CSS: 화천 화면과 공통 스타일.
• web/app.js: 데이터 로딩·검색·시설 정보·화면 제어.
• web/renderer.js, geometry.js, math.js: 기존 WebGL 렌더링·형상·좌표 계산.
• web/data/network.json: 실행에 필요한 변환된 화천 관망 데이터.
• web/fonts/: Pretendard 글꼴과 원문 라이선스.

데이터 출처와 이용 범위

제공 자료 HC_A.inp를 변환한 network.json을 그대로 포함합니다. 원본 SHA-256은 JSON의 meta.sha256에 기록되어 있으며 변환 당시 원본과 일치했습니다. 맨홀 805개, 방류구 9개, 저류시설 1개, 관로 843개, 펌프 3개, 위어 1개를 포함합니다. 원본 INP·도면·PDF와 변환 도구는 이번 실행용 제출 범위에서 제외했습니다.

이 저장소에는 실행에 필요한 JSON을 포함하며, 시설 ID·좌표·제원 등 실제 자료의 회사 Gitea 제출 허용 여부와 저장소 공개 범위는 담당자 확인이 필요합니다. 원자료의 소유자·이용허락 문서는 확인되지 않았습니다.

별도 외부 JavaScript 라이브러리는 포함하지 않습니다. Pretendard Variable 1.3.9는 해당 버전 공식 라이선스의 SIL OFL 1.1을 따르며 web/fonts/LICENSE.txt를 함께 제공합니다. 프로젝트 자체 코드의 라이선스와 회사 제출 범위는 미확정이므로 임의의 오픈소스 라이선스는 부여하지 않았습니다.

주요 미확정 사항

• 좌표계·XY 단위는 미확인으로, XY 1단위=1m를 가정합니다.
• 맨홀 내경 1.2m는 표현용 가정이며 실제 벽 두께·시공 선형·측량 지반고는 복원하지 않습니다.
• 좌표 누락·겹침, 입력 길이와 좌표 거리 차이, 입력 방향 기준 역경사 등이 남아 있습니다. 화면의 기존 데이터 점검 항목은 오류 확정이나 검증 완료를 뜻하지 않습니다.
• 표시·계산의 정확성과 브라우저별 동작에 대한 정식 검증은 별도 과제입니다. 개선·검증 계획은 향후 Gitea 이슈로 관리합니다.

검증

원본 INP는 저장소에 포함하지 않습니다. 별도로 준비한 파일 경로를 지정합니다.

python3 tools/validate_network.py --inp "/path/to/HC_A.inp" --output test-results/data-validation.json
python3 -m unittest discover -s tests -p 'test_*.py' -v

첫 명령의 종료 코드는 0=일치, 1=불일치, 2=입력 오류입니다. ID·수량·좌표·표고·접속·길이·단면 및 배치 제외 사유를 비교합니다. 수리 계산이나 실측 형상의 정확성을 인증하는 검사는 아닙니다.

화면 검증은 개발용 Playwright를 별도로 설치하고, 다른 터미널에서 python3 start.py --port 8081을 실행한 상태로 수행합니다. 웹사이트 실행 자체에는 Node.js가 필요하지 않습니다.

npm install
npx playwright install chromium
VIEWER_URL=http://127.0.0.1:8081/ npm run test:ui

Linux에서 브라우저 실행에 필요한 시스템 패키지가 없으면 Playwright의 설치 안내를 따릅니다. 다른 주소는 VIEWER_URL, 설치된 Chrome/Edge는 PLAYWRIGHT_CHANNEL=chrome 또는 msedge 환경변수로 지정합니다. 결과 JSON과 화면 이미지는 Git에서 제외되는 test-results/에 저장합니다. 검사 범위와 실행 결과는 이슈 #1에서 관리합니다.