판도연구소 v0.36.0

1801년 이후의 세계 역사 지도와 국가·영토 속성을 탐색하는 웹 열람기이며, Windows에서는 같은 지도 엔진을 이용한 읽기 전용 검수기를 제공합니다. Natural Earth 5.1.1의 1:10m 국가 데이터와 지형 음영, HydroRIVERS 강·Natural Earth 호수를 사용합니다.

이 저장소는 PC·모바일 웹 열람기, Windows 검수기, 공통 C++ 코어, 조사·검증 보고서를 함께 관리합니다. apps/viewer가 공개 웹과 Windows 검수기의 공통 UI 정본입니다. Android 네이티브 앱은 폐기되었고 모바일 브라우저는 계속 지원합니다.

v0.34.0부터 분포는 고정된 언어·민족·종교 분류 대신 이름·단위·숫자값으로 관리합니다. 소수·0·음수를 저장할 수 있고, 분포별 자동 또는 직접 지정한 값 범위로 색 농도를 정합니다. 보기 메뉴에서는 모든 분포를 겹쳐 보거나 한 분포만 표시할 수 있습니다.

개발 브랜치·워크트리 운영

웹·앱 공통 작업 브랜치(work/ui, work/objects, work/gis, work/places)와 분야별 상설 로컬 워크트리 재사용 원칙은 브랜치·워크트리 운영 정책을 참고하세요. 개발 에이전트의 필수 규칙은 AGENTS.md에 정리되어 있습니다. 작업별로 브랜치·워크트리를 새로 만들거나 작업 종료 시 자동 삭제하지 않습니다.

조사·검증 보고서는 보고서 색인에서 분야와 상태별로 찾을 수 있습니다.

공개 웹은 main의 config/library-data.json에 고정한 자료만 사용합니다. 완료한 자료의 보관·푸시·원격 확인 후 해당 핀을 main에 반영하면 웹 배포와 실제 응답 확인까지 자동으로 이어집니다. 작업 중 저장·동기화와 보고서 보관은 공개 게시를 발생시키지 않습니다. 자세한 절차는 외부 라이브러리 자료를 참고하세요.

로컬 실행

먼저 pnpm.cmd deps:prepare로 공용 의존성을 준비합니다.

명령	용도
pnpm.cmd dev:web	PC·모바일 웹, localhost:4173
pnpm.cmd dev:editor	Windows 검수기용 개발 서버(내부 호환 명칭), localhost:4175
pnpm.cmd dev:windows	CI Windows 실행기와 개발 서버
pnpm.cmd build:web	viewer 전용 정적 산출물
pnpm.cmd build:windows	Windows 전용 CI 오프라인 설치 파일 요청·검증

소스와 생성물의 위치는 폴더·생성물 운영을 참고하세요. 생성 HTML을 직접 열지 말고 개발 서버를 사용합니다. Rust·Emscripten은 CI에서 준비하며, Android SDK/NDK는 더 이상 앱 빌드에 사용하지 않습니다.

검사 실행

pnpm install --frozen-lockfile 후 변경 범위에 맞는 pnpm lint, pnpm check:architecture, pnpm test:unit, pnpm test:browser -- <파일>을 실행합니다. 전체 검사는 pnpm test입니다.

Windows에서 PowerShell 실행 정책이 pnpm.ps1을 막으면 pnpm.cmd를 사용합니다. GIS 생성기와 관련 검사는 Node.js와 기능별 네이티브 도구를 사용합니다.

현재 계약으로 검사 파일과 CI를 검수한 범위·실행 증거는 검사 최신화 기록에 기록합니다.

GitHub Pages 배포

main의 웹 파일만 Web-only GitHub Pages가 GitHub Actions artifact로 게시합니다. 앱 소스와 C++ 소스는 게시 파일에서 제외합니다. Pages 설정의 게시 방식은 GitHub Actions입니다.

모든 경로는 저장소 하위 URL에서도 동작하도록 상대경로로 구성되어 있습니다. .nojekyll도 포함되어 있습니다.

정적 파일을 배포하기 전에는 pnpm generate:build-meta로 현재 앱 버전과 배포 build ID를 반영한 자산 메타데이터를 생성하고, pnpm check:version으로 HTML·스크립트·Worker·캐시 revision의 일치를 확인합니다.

반응형 작업공간

작업공간은 화면 너비에 따라 세 단계로 전환됩니다. 넓음·중간 화면에서는 상단 보기, 지도 하단의 추가·검색 작업바와 별도 편집창을 사용합니다. 799px 이하에서는 하단의 추가 / 검색 / 편집 / 보기 탐색으로 같은 DOM의 논모달 바텀시트를 엽니다.

화면 크기나 방향이 바뀌어도 선택 객체, 입력 중인 편집선과 지도 카메라는 유지됩니다. 패널의 열림 상태는 임시 UI 상태이며 자동저장이나 GeoPackage에는 기록되지 않습니다.

변경 이력

v0.31.0에서는 지도·레이어·추가·편집 패널을 공통 Surface 셸과 탭 구조로 정리하고, 편집창에 정보·편집·관계 탭을 도입했습니다. 추가창은 만들기·라이브러리 경로를 유지하면서 공통 객체 분류와 Command Row 표현을 사용하며, build metadata로 앱·자산 버전을 일치시킵니다.

v0.30.0에서는 시작 과정을 미리보기·편집 가능·고화질 지도의 세 단계로 분리했습니다. 국가 원본이 준비되면 GPU 메시를 기다리지 않고 편집을 시작할 수 있으며, 기기·네트워크에 따라 원본 요청을 병렬 또는 순차 처리합니다. 시작 자산은 스트리밍으로 압축을 풀고 버전별 Cache Storage에 보관하며, 손상된 항목만 지운 뒤 자동으로 다시 받습니다.

v0.29.0에서는 프로젝트 레이어와 분리된 국가·지역 라이브러리를 추가했습니다. 안정적 libraryId, 다국어 이름·별칭, 존속 기간, 시대별 GeometryVersion, 출처·불확실성을 검색·미리보기하고 독립 프로젝트 인스턴스로 추가할 수 있습니다. 현존 국가는 기존 Natural Earth 데이터를 어댑터로 공급하며, 과거 국가 시험 항목은 근사 경계·낮은 신뢰도를 명시합니다. WorldSnapshot은 원본을 변경하지 않는 템플릿으로 등록됩니다.

v0.28.0에서는 프로젝트 레이어와 분리된 국가·지역 라이브러리를 추가했습니다. 안정적 libraryId, 다국어 이름·별칭, 존속 기간, 시대별 GeometryVersion, 출처·불확실성을 검색·미리보기하고 독립 프로젝트 인스턴스로 추가할 수 있습니다. 현존 국가는 기존 Natural Earth 데이터를 어댑터로 공급하며, 과거 국가 시험 항목은 근사 경계·낮은 신뢰도를 명시합니다. WorldSnapshot은 원본을 변경하지 않는 템플릿으로 등록됩니다.

v0.27.0에서는 판도연구소 프로젝트와 GIS 교환 형식을 분리하는 어댑터 계층을 추가했습니다. GeoPackage는 countries, territories, administrative, regions와 언어·민족·종교 분포를 독립 레이어로 내보내며, 안정적 ID·관계·기간·비율·불확실성을 속성으로 보존합니다. 영역 참조 분포는 내보내기 시에만 표준 Polygon/MultiPolygon으로 펼쳐지며 CRS는 EPSG:4326으로 명시됩니다.

v0.26.0에서는 언어·민족·종교를 DistributionLayer/DistributionEntry 공통 모델로 관리합니다. 하나의 지역에 여러 분포를 독립적인 0~100% 비율로 기록할 수 있고, TerritorialUnit 참조와 자유 Polygon/MultiPolygon을 모두 지원합니다. 지배적 분포와 선택 항목 비율 농도 렌더링을 제공하며, 국경·주권 편집은 문화 분포를 자동으로 변경하지 않습니다.

v0.25.0에서는 국가·권역·행정구역·지방을 TerritorialUnit 공통 API로 조회·선택·편집합니다. 직접 상위 영역(parentId)과 최종 주권국(sovereignId)을 분리하고, 일반 영역 연산은 공통 geometry 커널을 사용합니다. canonical 값은 각각 country, territory, admin, region입니다.

v0.24.0에서는 레이어 하위 항목의 장식 아이콘과 중복 국명 문구를 제거하고, 각 항목 오른쪽에 실행취소 가능한 삭제 버튼을 추가했습니다. 권역·행정구역은 기타 객체와 분리된 국가 영역으로 관리하며 국가별·행정 단계별 레이어, 전용 편집창, 나누기·합치기·영역 다시 지정·국가 이전·독립 작업을 제공합니다. 국가 Polygon은 국경과 해안선의 단일 기준이고, 명시적 구분을 시작한 부모의 남는 면적은 미지정 영역으로 보존됩니다. 이 관계는 프로젝트 상태와 GeoJSON·GeoPackage 입출력에 포함됩니다.

v0.23.0에서는 전역 탐색을 레이어 / 추가 / 편집으로 통일했습니다. Wide에서는 고정 레이어 패널과 접을 수 있는 모델리스 편집 패널, Compact에서는 세로 탐색 레일과 서랍, Mobile에서는 35%·60%·90% 논모달 바텀시트를 사용합니다. 패널을 열고 닫거나 시트 높이를 바꿔도 지도 중심·회전·배율과 플로팅 지도 도구 위치는 유지됩니다. 레이어 검색은 국가 코드도 찾되 목록에는 기술 ID를 표시하지 않으며, 긴 목록은 가상 렌더링합니다.

v0.22.0에서는 모바일의 지도·추가·편집 패널을 하나의 논모달 바텀시트 체계로 통합했습니다. 시트는 화면 하단과 좌우에 빈틈 없이 붙고 35%·60%·90% 높이로 조절할 수 있으며, 열린 상태에서도 지도 이동·확대·객체 선택이 가능합니다. 시트 높이가 바뀌어도 지도 카메라와 플로팅 도구 위치는 유지됩니다.

v0.21.0에서는 변경 국가만 교체하는 증분 GPU 메시와 영구 지도 편집 Worker를 도입했습니다. 합병·편입·국가 추가 계산 중에도 지도를 조작할 수 있으며, 지도 이동 중에는 데이터와 UI를 다시 만들지 않고 투영과 오버레이만 갱신합니다. 지형·수계 GPU 업로드와 자동저장은 프레임·유휴 예산에 맞춰 처리합니다.

v0.20.0에서는 지도와 연결된 레이어·편집 패널을 화면 폭과 관계없이 논모달로 통일했습니다. 모바일 패널은 기본·중간·최대 높이의 3단 스냅 바텀시트로 동작하며, 열린 상태에서도 지도 이동·확대·선택이 가능합니다. 파일 메뉴는 별도의 최상위 모달 오버레이로 분리해 편집 패널 위에서도 항상 조작할 수 있습니다.

v0.19.2에서는 상위 레이어를 공통 폴더 아이콘으로 통일하고 국가 레이어 잠금을 열린·잠긴 자물쇠 아이콘으로 표시합니다. 체크박스는 선택 시 내부만 강조색으로 채우고 외곽선은 중립색을 유지합니다.

v0.19.1에서는 하단 상태 정보를 좌·중·우로 분산하지 않고 지도 가용 영역 왼쪽의 한 묶음으로 정렬했습니다. 하단바 배경과 콘텐츠 영역을 분리하고 과거 flex·grid 중복 규칙을 제거해 패널 개폐와 화면 폭 변화에도 정보 순서와 간격이 유지됩니다.

v0.19.0에서는 국가·지명·지형지물·수계 편집창을 하나의 공용 셸과 컴포넌트 체계로 통합했습니다. 빈 상태, 정보 카드, 작업 버튼, 상세 정보와 삭제 영역이 객체 종류와 화면 크기에 관계없이 같은 구조와 여백을 사용합니다.

v0.18.2에서는 지도 위의 독립 현재 작업 카드를 제거하고 작업명·현재 단계·짧은 안내·완료 버튼을 상단 작업 도크에 통합했습니다. 대상 선택 개수는 긴 안내문 대신 완료·합병 버튼에 표시합니다.

v0.18.1에서는 편집 대상 유형 배지를 완전히 제거하고, 패널 닫기 버튼의 여백과 수계 정보 카드의 중첩 테두리를 정리했습니다. v0.18.0에서 통합한 공용 UI 규격은 그대로 유지합니다.

v0.18.0에서는 버튼, 세그먼트, 펼침 행, 선택 입력, 폼, 카드와 도구막대를 하나의 공용 UI 규격으로 통합했습니다. 화면 폭과 테마가 달라져도 동일한 역할은 같은 아이콘, 높이, 모서리, 테두리와 상호작용 상태를 사용합니다.

v0.17.0에서는 평상시에 배율만 남기고 좌표·작업·선택 정보를 필요한 순간에만 표시합니다. 레이어 개수와 반복 안내를 제거하고, 내장 수계의 출처·레이어 정보는 접힌 데이터 정보로 정리했습니다.

v0.16.4에서는 모바일 시트 헤더의 제목·닫기 버튼 정렬과 가용 높이를 통일하고, 사용할 수 없는 실행취소·다시실행 도크는 숨깁니다. 상태줄은 보기 정보 / 현재 작업 / 선택 대상 순서로 재구성하며 compact 화면에서도 왼쪽 끝까지 이어집니다.

v0.16.3에서는 기본 작업 상태를 하단 상태줄로 옮기고 실제 편집 안내만 지도 상단 중앙에 표시합니다. 편집 서랍은 상태줄 위에서 끝나도록 높이와 내부 카드 밀도를 조정해 상태줄이 화면 끝까지 이어집니다.

v0.16.2에서는 현재 작업 배지의 두 텍스트를 같은 크기로 정렬하고, 모바일 확대 도크를 다른 플로팅 도구와 같은 여백으로 통일했습니다. 중복 배율 표시는 제거하고 하단 상태줄에서만 제공합니다.

v0.16.1에서는 모바일 시트의 텍스트 닫기 버튼을 공통 아이콘 버튼으로 교체하고, 지도 투영 세그먼트의 외곽 높이를 다른 지도 도구와 동일한 42px로 맞췄습니다.

v0.16.0에서는 지도 크기와 패널 전환을 분리한 지도 우선 반응형 작업 공간을 도입했습니다. 1360px 이상에서는 레이어 패널과 모델리스 편집 서랍, 800~1359px에서는 세로 탐색 레일과 양쪽 서랍, 799px 이하에서는 하단 탐색과 모달 시트를 사용합니다. 지도 카메라와 편집 상태는 레이아웃 전환 중에도 유지됩니다.

v0.15.0에서는 공식 Pretendard v1.3.9 Variable 글꼴을 내장하고, 지도 라벨부터 모달 제목까지 글자 크기·굵기·행간을 역할별 체계로 통일했습니다. 작업 안내·알림·오류 문구는 간결한 존댓말과 일관된 영토 편집 용어를 사용합니다.

v0.14.4에서는 전체 지도 맞춤과 지구본 투영에 서로 다른 아이콘을 사용하고, 투영법과 영토 선택 방식의 세그먼트를 선택 항목 전체가 강조되는 형태로 통일했습니다.

v0.14.3에서는 영토 선택 방식을 경계 그리기 / 영토 선택으로 간소화하고, 영토 편입과 국가 합병에서 여러 대상국을 한 번에 선택할 수 있습니다. 각 작업은 한 번의 실행취소로 복원됩니다.

v0.14.2에서는 사이드바의 보기 섹션을 제거하고 지구본·평면 전환을 지도 도구막대로 옮겼습니다. 모바일에서는 같은 전환 버튼이 지도·레이어 시트 상단에 표시되며, 지도 엔진 정보는 하단 상태줄에서 확인할 수 있습니다.

v0.14.1에서는 영토 선택 작업 바를 지도 하단에서 상단 중앙의 간결한 명령 도크로 옮겼습니다. 국가 추가와 영토 편입은 선으로 나누기와 조각 선택 탭을 사용하며, 기존 편집 흐름과 단축키는 그대로 유지합니다.

v0.14.0에서는 스크롤바가 나타날 때 패널 내용이 옆으로 밀리지 않도록 폭을 고정하고, 글꼴·컨트롤·카드의 위계를 하나의 UI 체계로 통합했습니다. 국가 합병은 대상 국가 선택 즉시 완료되며, 국가 추가와 영토 편입은 국경선으로 나누기와 영토 조각 선택을 명시적인 방식 탭으로 제공합니다.

v0.13.3에서는 펼친 레이어 폴더와 클릭한 버튼에 남던 사각 테두리를 제거하고, 키보드 탐색에서만 포커스 표시가 나타나도록 정리했습니다. 보조 문구·본문·지도 라벨과 관련 컨트롤 크기를 함께 확대했으며, 내장 수계 레이어의 화면 표시명을 강, 호수로 통일했습니다.

v0.13.2에서는 보기에 투영법과 지도 엔진만 남기고 지형 표시를 독립된 최상위 레이어 폴더로 분리했습니다. 폴더에서 국가 색상 유지 또는 지형 높낮이 색상을 선택하며, 국가 색상 유지의 명암은 일관된 기본값으로 표시합니다. 내장 강과 호수는 수동 색상 설정 없이 현재 표시 중인 바다 계열을 자동으로 따릅니다.

v0.13.1에서는 지형지물 하위 레이어를 강, 호수, 기타 객체와 객체 수만 표시하도록 간소화해 좁은 패널에서도 레이어명을 읽기 쉽게 만들었습니다. Hydro·Natural Earth 출처와 수계 준비 상태, 재시도 안내는 기존 상단 알림과 레이어 선택 안내에서 계속 제공합니다.

v0.13.0에서는 UI 본문을 14px, 보조 문구를 최소 12px로 통일하고 국가·지명 라벨도 확대했습니다. 선택 국가는 기존 2px 외곽선과 함께 테마 강조색의 옅은 반투명 면으로 표시됩니다. 영토 편입을 시작하거나 영토를 가져올 국가를 선택해도 현재 지구본 회전·중심·확대율을 바꾸지 않습니다.

v0.12.6에서는 국가 외곽선에서 극점·날짜변경선용 인공 폐합 구간을 제외하고, 국가 채움용 Polygon은 그대로 보존합니다. 국가 색상 유지는 국가 면 스텐실로 육지만 높낮이 명암을 더하며, 지형 높낮이 색상은 강·호수가 없는 Natural Earth HYP_HR_SR 육지와 기존 해저 지형을 합성합니다. 강과 호수는 각각 흰색 또는 현재 테마의 바다색을 선택할 수 있습니다.

v0.12.5에서는 수계 metadata를 표시용 core와 상세 출처용 detail로 분리합니다. 긴 원본 reach 목록이 들은 detail은 수계를 선택하거나 편집용 복사를 실행할 때만 지연 로드하며, WebGL 메인 스레드에는 GeoJSON 대신 GPU TypedArray와 고정 크기 descriptor만 전달합니다. Canvas 대체 경로는 Hydro Worker와 Canvas Worker를 MessageChannel로 직접 연결해, 메인 스레드에는 좌표 대신 완성된 ImageBitmap과 선택 ID만 보냅니다.

v0.12.0에서는 지형 음영과 Natural Earth 수계를 도입하고, 필요한 화면 단계의 타일만 불러오는 비차단 물리 데이터 로딩을 추가했습니다.

v0.11.2에서는 지도·레이어·편집 패널의 작업 흐름과 상태 안내를 정리하고, 강·호수 생성과 지형지물 레이어 표시를 추가했습니다.

v0.11.0에서는 화면 너비에 따라 패널과 편집창이 전환되는 반응형 작업공간을 도입했습니다.

v0.10.3에서는 운영체제·브라우저의 prefers-color-scheme에 따른 밝은 테마와 어두운 테마를 지원했습니다.

v0.10.2에서는 레이어 폴더와 국가 GPU 메시를 추가해 객체 탐색과 WebGL 렌더링 기반을 마련했습니다.

v0.10.0에서는 QGIS 벡터 파일과 GeoPackage를 가져오고 저장하는 GIS 교환 기능을 추가했습니다.

국가 선택은 지도의 기본 동작입니다. 새 국가·지명·강·호수는 지도 위 추가 메뉴에서 만들며, 활성 편집의 완료·선택 방식 전환·취소는 지도 하단 작업 바에만 표시됩니다. 진행·성공·오류 알림은 상단 중앙 한곳에서 안내합니다.

객체 탐색과 표시

객체는 지도 또는 하단 검색으로 찾고 선택합니다. 국가·하위단위·지방·분포·지명·강·호수·지형의 표시 여부와 세부 표현은 보기에서 조절합니다. 좁은 화면에서는 같은 설정이 보기 시트에 표시되며 설정값과 컨트롤을 복제하지 않습니다. 내장 수계는 잠겨 있으며 선택 후 편집용 복사 만들기를 사용하면 원본을 숨기고 같은 형상의 편집 객체를 만들 수 있습니다. 표시 상태는 자동저장 및 GeoPackage의 pandolab_project_settings에 보존됩니다.

국가명은 해외 영토를 포함한 전체 중심점 대신 가장 큰 연결 영토 내부의 최적 지점에 자동 배치됩니다.

글꼴

인터페이스와 지도 라벨은 Pretendard v1.3.9의 PretendardVariable.woff2를 저장소에 포함해 사용합니다. 글꼴은 SIL Open Font License 1.1로 배포되며 라이선스 전문은 assets/fonts/pretendard-v1.3.9/LICENSE.txt에 있습니다. 포함된 WOFF2의 SHA-256은 9599F12FD42FC0BCE1CD50B47A0C022E108D7AA64DD0D1BB0ED44F3282D900B4입니다.

시스템 테마

판도연구소는 운영체제·브라우저의 prefers-color-scheme 설정을 따라 밝은 테마와 어두운 테마를 자동 전환합니다. 실행 중 시스템 설정이 바뀌어도 현재 카메라, 선택 객체와 편집 중인 선은 유지되며 테마는 프로젝트나 GeoPackage에 저장되지 않습니다.

밝은 지도의 바다 #FFFFFF, 기본 육지 #CCCCCC, 국경 #FFFFFF, 지구본 외곽선 #000000, 격자 #AAAAAA 배색은 Milenioscuro의 Wikimedia Commons 파일 Russian Empire (orthographic projection).svg를 참조했습니다. 해당 SVG는 CC BY-SA 3.0으로 제공됩니다. 판도연구소는 색상 토큰만 참조했으며 사용자 지정 및 GIS에서 가져온 국가 색상은 두 테마에서 그대로 유지됩니다.

GPU 메시

국가 면은 원본 국경을 제거하거나 단순화하지 않고 WebGL2·WebGL1에서 렌더링합니다. 일반 영토는 날짜변경선을 해제한 경위도 평면, 극지 영토는 극 중심 방위평면에서 삼각분할과 세분화를 함께 수행해 렌더링 삼각형이 바다로 이탈하지 않게 합니다. 모든 렌더링 변의 구면 각거리는 0.499° 이하입니다.

내장 메시를 다시 생성하려면 저장소 루트에서 node tools/build-world-mesh.mjs를 실행합니다. 이 과정은 배포 시 필요하지 않으며 정적 사이트는 생성된 메시를 바로 읽습니다.

지형 표시와 수계

보기 패널에서 국가 색상 유지와 지형 높낮이 색상을 전환할 수 있습니다. 웹 WebGL과 앱은 ETOPO 2022 기반 DEM 0.13.3의 고도·음영과 tint를 사용합니다. Canvas Worker도 현재 화면의 DEM에서 상세 색상·음영을 생성합니다. 초기 표시와 DEM 실패에는 같은 DEM에서 만든 약 3.37MB의 LOD 0·1 미리보기를 사용하고, 앱에 이 미리보기를 내장합니다. 미리보기 RGB는 지형색·수심, A는 흑백 음영 데이터입니다. 생성·검증과 폐기 자료 정책은 DEM 지형 표시 계약에 기록합니다.

강은 HydroRIVERS 1.0을 사용합니다. ORD_STRA + 4×log10(DIS_AV_CMS) - 0.5×log10(UPLAND_SKM) 중요도 기준으로 선별하고, 최종 유역면적 2,500㎢ 이상인 유역은 대표 본류를 발원부부터 하구·내륙 종점까지 보존합니다. 내장 수계의 표시 단계는 지도 확대율 3.5배·7배·14배·28배에서 순차 활성화합니다. 이 배율 기준은 기존 압축 형상 및 2,500㎢ 본류 보존 기준을 변경하지 않고 웹·앱의 표시와 타일 요청에 동일하게 적용합니다. 추가 본류는 최고 세부 단계부터만 표시합니다. 같은 MAIN_RIV에 속한 본류와 표시 지류는 하나의 논리적 수계로 묶여 선택·숨김·편집용 복사가 함께 적용되며, 지류별 명칭과 역할은 상세 메타데이터에 보존됩니다. 강 너비는 유량과 하천 차수로 계산하고 하류가 상류보다 가늘어지지 않게 보정합니다. 선택된 Hydro 원본 꼭짓점은 단순화하지 않고 1e-6° 정밀도로 저장합니다.

한국어 수계명은 독립 기관 자료·Natural Earth와 검수 교정표를 바탕으로 확인합니다. 내장 HydroRIVERS v0.13.4 자료에는 OpenStreetMap의 명칭·수계 관계를 포함하지 않으며, 독립적인 형상 대응을 확정하지 못한 수계는 안정적인 미명명 수계 ID로 표시합니다. 강·천·호·호수 접미사는 고유명과 붙여 쓰며 다뉴브강은 도나우강으로 교정합니다. 검증된 이름이 없는 지류에는 이름을 임의 생성하지 않고 대표 수계에 포함하며, 수계 전체에 이름이 없을 때만 안정적인 ID가 붙은 미명명 수계로 표시합니다. 하천 이름·관계는 OSM 파생 자료 없이 배포하며 원래 HydroRIVERS의 강 좌표와 인덱스는 보존합니다. 바이코누르 임대구역 경계 등의 다른 OSM 파생 형상은 해당 객체 출처 및 지도 귀속 표기에 명시합니다.

호수는 Natural Earth 5.0.0 1:10m 전 세계 기본 Lakes + Reservoirs 1,355개를 사용합니다. 유럽·북미·호주 지역 보충 자료와 HydroLAKES 형상은 렌더링하지 않아 전 세계 표시 밀도를 일정하게 유지합니다. 162,852개 원본 좌표는 단순화하지 않습니다.

내장 Natural Earth 국가 사이의 공유국경을 10km 이상 따라가는 강은 거리·표본 점유율·방향 조건을 모두 통과한 구간만 진입점·이탈점에서 분할해 정확한 공유국경 경로로 교체합니다. 한 Hydro reach의 일부만 국경 역할을 해도 해당 구간만 정렬하며, 단순 횡단이나 짧은 평행 구간은 제외합니다. 국가 폴리곤과 사용자 편집 국경은 변경하지 않습니다. 정렬 전 Hydro 좌표와 국가 쌍은 상세 메타데이터에 보존하고, 정렬 구간은 같은 논리 수계 ID를 유지한 채 국경 위에 다시 그립니다.

초기 실행에서는 100KiB 미만의 manifest와 압축 metadata를 Worker에서 읽고, 현재 화면과 확대 단계에 필요한 바이너리 타일만 복원합니다. 표시 pack에는 좌표만 들어 있으며 GeoJSON은 선택·편집용 복사 시에만 복원합니다. 인접 Range 요청은 합쳐 받고 GPU 업로드는 프레임별로 나눕니다. WebGL 캐시는 데스크톱 96MiB, 모바일 48MiB로 제한합니다. 자동 수계 라벨은 포함하지 않습니다.

수계 metadata는 표시용 core와 상세 출처용 detail로 분리합니다. 긴 원본 reach 목록이 들은 detail은 수계를 선택하거나 편집용 복사를 실행할 때만 지연 로드하며, WebGL 메인 스레드에는 GeoJSON 대신 GPU TypedArray와 고정 크기 descriptor만 전달합니다. Canvas 대체 경로는 Hydro Worker와 Canvas Worker를 MessageChannel로 직접 연결해, 메인 스레드에는 좌표 대신 완성된 ImageBitmap과 선택 ID만 보냅니다.

물리 자료 생성기는 Natural Earth 원본을 읽어 별도의 새 후보 폴더에 생성합니다. 수계는 GDAL ogr2ogr와 Node가, 지형은 Node와 소스가 일치하는 physical-raster, terrain-preview, map-image C++ 도구가 처리합니다. Windows에서 GDAL DLL이 PATH에 없다면 PANDO_PHYSICAL_RASTER_GDAL_BIN으로 해당 절대 폴더를 지정합니다. 기존 산출물과 원본은 덮어쓰지 않습니다. 작은 고정 사례는 비교했으나 실제 TIFF 전체와 대형 입력 성능은 아직 확인하지 않았으므로 후보 결과는 별도로 검토합니다.

node tools/build-physical-data.mjs <Natural-Earth-원본-폴더> <새-후보-폴더> --countries assets/data/countries-ne-5.1.1.geojson

Hydro 전 세계 보충 자료 캘리브레이션

tools/gis/calibrate-hydro.mjs는 HydroRIVERS·HydroLAKES를 현재 Natural Earth 기본+지역 보충 수계와 비교하는 분석 전용 도구입니다. 유럽·북미·호주에 동일한 중요도 공식과 min_zoom 6.0·6.7·7.0·7.5 경계를 적용하고, 한반도는 별도 검증 범위로 사용합니다. Natural Earth 기본 수계 중복 제거, 단계별 길이·화면 점유율·호수 개수, 하천 체인 결합 시 좌표 보존과 예상 전 세계 용량을 함께 계산합니다.

node tools/gis/calibrate-hydro.mjs `
  --hydrorivers-root <HydroRIVERS-대륙별-폴더> `
  --hydrolakes <HydroLAKES_polys_v10.shp> `
  --natural-earth-root assets/data/hydro `
  --output reports/hydro/calibration/<새-분석-폴더>

소스와 일치하는 네이티브 Hydro 계산기·GEOS 점 검사기·이미지/미리보기 도구가 필요합니다. Windows에서는 PANDO_HYDRO_RUNTIME_ROOT에 일치하는 OSGeo4W 경로를 지정합니다. 분석 출력은 assets/data 아래로 지정할 수 없으며 기존 폴더를 덮어쓰지 않습니다. 캘리브레이션 원본 결과는 reports/hydro/calibration/에 보존되어 있습니다.

실제 v0.13.1 수계 샤드는 다음 명령으로 다시 생성합니다. 아홉 개 HydroRIVERS 대륙 Shapefile, 저장소의 Natural Earth lakes_base.geojson, 검수 교정표와 빌드용 OSM waterway 관계 내보내기를 사용합니다. 생성기는 중형 본류를 하구까지 폐합하고, 수계 단위 논리 ID와 본류·지류 역할을 만든 뒤 내장 공유국경과 일치하는 세부 구간을 표시용 형상으로 정렬합니다. 결과에는 Natural Earth 호수, 단일 공간 인덱스와 4MiB 이하 정적 샤드가 포함됩니다. 표시 강의 종점은 바다·Natural Earth 호수·합류점·내륙 유역으로 분류하고, 같은 육지 안의 명확한 하구만 최대 25km 범위에서 연결합니다. Hydro 원본 연결망 자체가 해안에서 멀리 끊겨 안전하게 복구할 수 없는 경우에는 임의의 직선을 만들지 않고 해당 논리 수계 전체를 제외하며 manifest 통계에 남깁니다.

node tools/gis/build-hydro.mjs `
  --hydrorivers-root <HydroRIVERS-원본-폴더> `
  --natural-earth-root assets/data/hydro `
  --drainage-free-raster <HYP_HR_SR.tif> `
  --osm-waterways assets/data/hydro/osm-waterway-ko-v0.13.0.json `
  --hydronym-overrides assets/data/hydro/hydronym-ko-overrides.json `
  --output <새-작업-출력-폴더>

생성기는 기존 출력과 운영 자료를 덮어쓰지 않습니다. 원본과 일치하는 Hydro 연결·공간 검사·인코딩 도구와 GDAL 래스터 도구가 필요합니다.

앱은 현재 화면의 샤드 범위를 먼저 불러온 뒤 지도 조작이 2초 동안 없을 때 전 세계 압축 샤드를 Cache Storage에 저장합니다. 지도 조작이나 전경 요청이 시작되면 다운로드를 일시 중지합니다. 압축 원본만 영구 저장하며 해제 형상과 GPU 버퍼는 데스크톱 96MiB, 모바일 48MiB LRU 범위를 유지합니다.

QGIS 벡터 파일

GIS 파일 열기에서 다음 형식을 가져올 수 있습니다.

• GeoPackage (.gpkg)
• QGIS 프로젝트 (.qgz, .qgs)와 함께 선택한 참조 벡터 파일
• Shapefile 구성 파일 (.shp, .shx, .dbf, .prj, .cpg) 및 .shz, .zip
• GeoJSON, KML/KMZ, GML/XML, FlatGeobuf

가져오기 마법사에서 Polygon/MultiPolygon 국가 레이어, ID·국명·색상 필드, CRS와 열기 방식을 지정합니다. CRS가 없는 자료는 EPSG 코드를 입력해야 합니다. 같은 ID의 여러 행은 하나의 MultiPolygon 국가로 묶을 수 있습니다.

QGS/QGZ는 데이터 자체를 항상 포함하지 않으므로, 프로젝트가 참조하는 GPKG나 Shapefile 구성 파일도 함께 선택해야 합니다. PostGIS 같은 데이터베이스, WMS/WFS, 원격 URL, 래스터, 인쇄 레이아웃, 플러그인과 매크로는 지원하거나 실행하지 않습니다.

권역·행정구역·지방과 해안선

• 권역: 국가 국토를 구분하는 전용 영역입니다. 나누기·인접 권역 합치기·영역 다시 지정·다른 국가로 이전·독립 국가 전환을 지원합니다.
• 행정구역: 국가·권역·상위 행정구역을 부모로 가지는 전용 영역입니다. 부모 관계에 따라 1급·2급 단계를 자동 계산하고 같은 부모·단계의 인접 구역만 합칠 수 있습니다.
• 민족·종교·언어: 소유권과 분리된 주제 영역입니다. 원본 좌표는 보존하고 화면에서는 현재 육지 안에만 표시하며, 같은 역할끼리 나누거나 합칠 수 있습니다.
• 강·호수: 수계 객체로 유지하며 국가 소유권이나 영토 연산에 참여하지 않습니다.

국가 Polygon이 국경과 해안선의 단일 기준입니다. 권역·지방·행정구역 외곽은 따로 꼭짓점을 움직이지 않고 안전한 나누기·합치기·영역 다시 지정으로만 변경합니다. 부모별 영역을 만들기 시작하면 이름 없는 나머지 면적을 미지정 지역 또는 미지정 행정구역으로 유지해 국토에 구멍이 생기지 않게 합니다. 국가 합병·편입·분리 때 관계된 영역의 소속과 형상도 같은 실행취소 단위로 갱신됩니다.

저장

GeoPackage 저장은 원본 입력 파일을 수정하지 않고 판도연구소-프로젝트.gpkg를 새로 만듭니다.

• countries: EPSG:4326 MultiPolygon 국가와 원본 속성
• places: 지명 Point
• generic_features_point, generic_features_line, generic_features_polygon: 기타 객체의 Point·Line·Polygon geometry
• territories: 국가별 권역 MultiPolygon과 소속·상태 관계
• administrative_areas: 단계별 행정구역 MultiPolygon과 부모 관계
• pandolab_country_assets: 국기 이미지 BLOB
• pandolab_project_settings: 투영법, 카메라, 레이어 상태와 내장 수계 데이터 버전
• pandolab_source_info: 원본 파일·드라이버·CRS·필드 매핑·SHA-256

내장 전 세계 수계는 파일 용량이 중복되지 않도록 GeoPackage에 넣지 않습니다. 사용자가 만든 강·호수와 편집용 복사로 만든 객체는 canonical 수계 테이블에 저장되고 기타 객체는 generic_features_* 테이블에 저장됩니다. QGIS에서는 이 사용자 벡터를 일반 레이어로 열어 편집할 수 있고, 판도연구소로 다시 열면 국기·메모·화면 상태와 내장 수계 버전도 복원됩니다. 자동저장은 별도의 판도연구소 전용 IndexedDB에만 저장되며 공개 프로젝트 파일로 노출되지 않습니다.

지도 데이터와 라이선스

• Natural Earth 5.1.1 Admin 0 Countries, 1:10m (퍼블릭 도메인)
• Natural Earth 5.0.0 Rivers + Lake Centerlines / Lakes + Reservoirs, 1:10m (퍼블릭 도메인)
• HydroRIVERS 1.0 (HydroSHEDS 라이선스 및 인용 조건 적용)
• Natural Earth raster 3.2.0 Gray Earth / Cross-blended Hypsometric Tints, 21,600×10,800 (퍼블릭 도메인)
• 258개 국가·속령·분쟁 단위, 원본 좌표 548,471개
• gdal3.js 2.8.1 / GDAL 3.8.4 (LGPL-2.1-or-later)
• sql.js 1.14.2 (MIT)
• fflate 0.8.3 (MIT)

Natural Earth 자료는 이용 조건에 따라 퍼블릭 도메인으로 제공됩니다.

각 라이선스 원문은 assets/js/vendor의 해당 폴더에 포함되어 있습니다. GIS 런타임은 파일을 열거나 저장할 때만 지연 로딩됩니다.