데이터 폴더 입력 명세 — 스테이션기반 플레이어

웹플레이어가 동영상이 있는 폴더를 전달받아 재생할 때, 폴더 안에 어떤 파일이 어떤 형식으로 있어야 하는지를 정의한다. 근거: client/src/utils/geoData.ts(폴더 파서) 기준. 실데이터(v3.0, 대전조차장–회덕)로 검증.

1. 동작 개요

1. 사용자가 브라우저에서 폴더를 선택하면(<input type="file" webkitdirectory>), 폴더 내 전체 파일 목록이 플레이어에 전달된다.
2. 플레이어는 파일명 규칙으로 각 파일을 자동 식별·파싱한다(별도 설정 불필요).
3. 기준 이름 base = 영상 파일명에서 확장자를 뺀 것 (예: 상행)대전조차장-회덕.MP4 → base는 상행)대전조차장-회덕). 나머지 파일은 base 일치를 우선 매칭하고, 없으면 폴백 규칙으로 찾는다.

2. 폴더 구성 요약

예시 폴더 (실데이터 v3.0):

상행)대전조차장-회덕 데이터(v3.0)/
├── 상행)대전조차장-회덕.MP4          ← 영상 (base 기준)
├── 상행)대전조차장-회덕.csv          ← 드론 비행로그
├── 01)측점.csv                       ← 측점 (루트 또는 building/ 하위 모두 허용)
├── 상행)대전조차장-회덕.kmz          ← POI·구조물 원본
├── 상행)대전조차장-회덕.route.json   ← 노선 정보 (선택)
├── 상행)대전조차장-회덕.srt          ← (무시됨)
└── 상행)대전조차장-회덕.qgz          ← (무시됨, QGIS 작업파일)

3. 파일별 상세 명세

3.1 영상 — <base>.MP4

• 확장자: .mp4 또는 .webm (대소문자 무관). building/ 하위가 아닌 루트의 첫 번째 영상 파일을 사용한다.
• 코덱: 브라우저 직접 재생이므로 H.264 권장.
• 용량: 2GB 이상 가능 (URL.createObjectURL() 참조 방식 — 메모리에 통째로 올리지 않음).
• 이 파일명이 폴더 전체의 base 를 결정한다.

3.2 드론 비행로그 — <base>.csv

드론이 촬영과 동시에 기록한 프레임별 데이터. 헤더 이름으로 컬럼을 찾으며(순서 무관), 헤더가 깨졌을 때만 위치 인덱스로 폴백한다.

• 추가 컬럼(rel_alt, 5186x, 5186y, X좌표, Y좌표 등)이 있어도 무시되고 오류 없음.
• latitude 가 숫자가 아닌 행은 건너뜀.
• 파일 선택 규칙: 루트의 .csv 중 ① <base>.csv 정확 일치 우선, ② 없으면 파일명에 POI 가 없는 첫 .csv (영상명 비의존 폴백).
• fps 자동 산출: 최대 frame_cnt ÷ 영상 길이(초) → 표준 fps(24/25/29.97/30/50/60…)에 스냅. 따라서 비행로그의 프레임 수는 영상의 실제 프레임 수와 일치해야 한다.

3.3 측점 — 01)측점.csv (또는 측점.csv)

철도 노선 측량 성과. 시간↔︎측점 대응표(스테이션바)와 선로 중심선, POI 높이 보완의 근간 데이터.

• 파일 찾기 규칙 (3단 폴백): ① building/ 하위에서 파일명에 01)측점 포함 → ② 루트 포함 아무 위치에서 01)측점 포함 → ③ 파일명에 측점 포함.
• 컬럼 (헤더 이름 기준):

• 중심선 자동 생성: v2.0 이후 center.csv 가 없으므로, 측점을 이정 순으로 이어 만든 폴리라인이 선로 중심선이 된다. → 측점 정확도가 곧 측점 투영·POI 높이 보완의 정확도.

⚠️ 주의 (실데이터에서 발견): 상행 v3.0의 01)측점.csv 는 실측 표고가 z 컬럼에 있고 Z좌표 컬럼은 0.0 인데, 파서는 Z좌표_한국 → Z좌표 순서로만 읽으므로 표고가 0으로 로드된다. 하행 파일처럼 표고 컬럼명을 Z좌표_한국 으로 통일하거나, 파서에 z 컬럼 폴백 추가가 필요하다.

3.4 POI·구조물 — <base>.kmz (또는 .kml)

POI·구조물의 유일한 소스다 (building/ 하위 02)~06) CSV는 더 이상 읽지 않음). 루트의 bare .kml 이 있으면 우선, 없으면 .kmz(zip)를 해제해 doc.kml 을 읽는다.

• KML 폴더 구조 → 분류 매핑:

• Placemark 좌표: <coordinates> 의 lon,lat[,alt] 우선. 없으면 description 속성 lat/lon. 한국 범위 검증(위도 33~39, 경도 124~132) 밖이면 버림.
• 속성(description): HTML <table> 의 (키, 값) 행으로 기재 — 구분, 연장(m), 시설종별(1종/2종/3종/기타), 시설물명, 출입문번호, source, category_clean, title, 표고(z/Z좌표/절대고도) 등. 구글어스 재저장본의 표 변형(<tbody>, 엔티티 등)도 허용.
• 표고: POI 속성에 z/절대고도 가 있으면 사용, 없으면 0 → 재생 시 최근접 측점 실측 표고로 보완된다.
• 누락 시: 경고 로그 후 POI·구조물 없이 동작(측점·드론·영상은 정상). CSV 폴백은 없다.

3.5 노선 기본 정보 — <base>.route.json (선택)

루트의 <base>.route.json 우선, 없으면 route.json. UTF-8 JSON.

{
  "routeInfo": {
    "name": "대전조차장-회덕",       // 노선명 (표시용)
    "direction": "상행",             // 방향 라벨
    "lengthKm": 4.25,                // 구간 연장 (km)
    "durationSec": 568,              // 영상 길이 (초)
    "startStationName": "대전",      // 시점역
    "endStationName": "신탄진",      // 종점역
    "stationTolerance": 20,          // 측점 인정 반경(m) — 기본 40
    "endStationGapMeters": 0         // 종점 미도착 거리(m) — 0이면 도착
  },
  "structures": [                    // (선택) 구조물 보정 — name 매칭으로 override
    {
      "name": "회덕천교",            // 괄호 이하 제거 후 부분일치 매칭
      "station": "158k400",          // 최우선: 이 측점값 위치에 배치 (숫자 m 또는 "158k400")
      "offset": -10,                 // 진행방향 ±N m 미세조정
      "startMileage": 158400,        // 매칭 실패 시 폴백 이정
      "endMileage": 158500,
      "lat": 36.4031, "lon": 127.4216   // 좌표 직접 지정도 가능
    }
  ]
}

• structures 항목은 KMZ 유래 구조물에 명시된 필드만 덮어쓰고, KMZ에 없는 항목은 새 구조물로 추가된다.

3.6 POI 위치 보정 — <base>_poi_overrides.json (선택)

영상에서 POI 라벨을 드래그(역투영) 해 보정한 좌표의 저장/배포 파일. 폴더에 있으면 로드 시 자동 적용된다.

{
  "baseName": "상행)대전조차장-회덕",
  "overrides": {
    "회덕터널": { "lat": 36.40312, "lon": 127.42169, "z": 66.1 }
  }
}

• overrides 없이 평면 맵({ "회덕터널": {…} })도 허용. z 는 정표고(m). POI title 정확 일치로 매칭.

4. 공통 규칙 (인코딩·파싱)

5. 파일 누락 시 동작

부록 — 구현 근거 (소스 위치)