# 화천군 관망도

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

## 실행

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

```bash
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는 [해당 버전 공식 라이선스](https://github.com/orioncactus/pretendard/blob/v1.3.9/LICENSE)의 SIL OFL 1.1을 따르며 `web/fonts/LICENSE.txt`를 함께 제공합니다. 프로젝트 자체 코드의 라이선스와 회사 제출 범위는 미확정이므로 임의의 오픈소스 라이선스는 부여하지 않았습니다.

## 주요 미확정 사항

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

## 검증

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

```bash
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가 필요하지 않습니다.

```bash
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에서 관리합니다.