Map Visualization 플러그인

이 글은 제삼자가 작성했으며 자동으로 번역되었습니다. 영어 원문 읽기

Beekeeper Studio 안에서 바로 쿼리 결과를 인터랙티브 지도에 표시하세요. 좌표, 지오메트리, 지명이 담긴 결과 세트라면 무엇이든 지정하고 표시 방식을 고르면 돼요: 점, 크기별 버블, 번호 마커, 클러스터, 히트맵, 경로, 흐름선, 채워진 영역 중에서요.

데모: 쿼리 결과를 버블, 히트맵, 클러스터, 미국 주, 이동 라인, GPS 경로로 표시

_{1.6배속 영상이에요. 원래 속도 영상 보기.}

설치

Beekeeper Studio는 커뮤니티 플러그인이 꺼진 상태로 제공돼요. user.config.ini(Linux는 ~/.config/beekeeper-studio/, macOS는 ~/Library/Application Support/beekeeper-studio/, Windows는 %APPDATA%\beekeeper-studio\)에서 켠 다음 앱을 다시 시작하세요:

[pluginSystem]
disabled = false
communityDisabled = false

플러그인이 플러그인 레지스트리에 등록되면 Tools → Manage Plugins에서 Map Visualization을 설치하세요. 그 전까지는 개발 섹션의 설명대로 빌드한 뒤 플러그인 폴더에 링크하면 돼요.

지도 열기

위치	동작
쿼리 결과 상태 표시줄의 Visualize → Map	선택한 셀을 지도에 표시해요. 아무것도 선택하지 않으면 전체 결과를 표시해요. 쿼리를 다시 실행하지 않아요.
테이블 뷰 상태 표시줄의 Visualize → Map	선택한 셀을 지도에 표시해요. 아무것도 선택하지 않으면 뷰의 필터를 적용해 테이블에 `SELECT * … LIMIT 10000`을 실행해요.
결과 그리드나 테이블 뷰의 왼쪽 위 모서리(또는 컬럼 헤더)를 우클릭 → Plot on Map	선택한 셀을 지도에 표시해요. 쿼리를 다시 실행하지 않아요.
쿼리 에디터에서 우클릭 → Plot Query on Map	선택한 텍스트(또는 커서 위치의 쿼리)를 실행하고 지도에 표시해요.
사이드바에서 테이블을 우클릭 → View on Map	해당 테이블에 `SELECT * … LIMIT 10000`을 실행해요.
새 탭 드롭다운 또는 Tools → New Map	전용 쿼리 입력창이 있는 지도 탭을 열어요(Ctrl/Cmd+Enter로 실행).

쿼리 결과는 탭 하단의 결과 테이블에도 표시되므로, 원본 행을 언제든 한 번의 클릭으로 볼 수 있어요.

위치 데이터 인식 방식

컬럼은 자동으로 감지돼요. 감지 결과는 Location 패널에서 직접 바꿀 수 있어요.

데이터	예시
위도/경도 컬럼	`lat`/`lng`, `latitude`/`longitude`, `pickup_lat`/`pickup_lon`, `storeLat`/`storeLng`; 십진 도(decimal degrees) 또는 DMS(`40°42'46"N`)
Web Mercator 미터	EPSG:3857의 `x`/`y`, 자동 변환
지오메트리 컬럼	PostGIS EWKB hex, WKB, WKT / EWKT, GeoJSON(텍스트 또는 객체), MySQL / GeoPackage 바이너리, `{lat, lng}` 또는 `{x, y}` 객체, Mongo GeoJSON 포인트
텍스트 좌표	`"40.7128, -74.0060"`, `(40.7, -74.0)`, `S33.92 E18.42`
지오해시	`dr5regw3p`
국가	이름, 별칭(`UK`, `South Korea`, `Côte d'Ivoire`), ISO alpha-2/3 또는 숫자 코드
미국 주	이름, 우편 약어, FIPS 코드
도시	`Paris`, `Paris, TX`, `London, Ontario`, 국가/주 컬럼으로 범위를 좁힐 수도 있어요; 약 34,000개 도시, 오프라인 지원
미국 ZIP 코드	`02134`, `02134-1234`, 또는 앞자리 0이 빠진 숫자

애매한 입력은 보수적으로 처리해요: 위도/경도 컬럼이 뒤바뀌었으면 (경고와 함께) 바로잡고, 모호한 도시 이름은 인구가 가장 많은 곳으로 해석하며, 정확한 중심점이 없는 ZIP 코드(사서함)는 3자리 ZIP 지역으로 대체하고, 위치를 찾지 못한 항목은 개수를 세요. 상태 표시줄의 “N개 위치 없음”을 클릭하면 해당 행을 테이블에서 볼 수 있어요. 다른 SRID의 투영 지오메트리는 ST_Transform(geom, 4326)을 쓰라는 힌트와 함께 알려 드려요.

표시 방식

레이어	용도	옵션
포인트	점, 버블, 번호 마커	컬럼 기준 크기(선형, 제곱근(면적 비례), 로그), 99번째 백분위수에서 이상치 제한, 범주나 숫자 기준 색상(선형, 로그, 분위수 구간; 순차형 또는 발산형), 라벨(행 번호 또는 컬럼), 불투명도
클러스터	서로 겹치는 수천 개의 포인트	클러스터별 개수 표시, 확대하면 분리
히트맵	밀도, 컬럼 기준 가중치 선택 가능	반경, 흐림, 가중치 배율. 강도를 줌 레벨별로 정규화해서 어떤 축척에서도 핫스팟이 보여요
경로	GPS 트랙, 이동 경로, 순서가 있는 방문	그룹 컬럼별로 경로 1개, 아무 컬럼(시간, 순번)이나 행 순서로 정렬; 시작/끝 마커
라인	출발지 → 도착지 흐름(이동, 배송)	도착지 컬럼, 곡선 또는 직선, 컬럼 기준 굵기와 색상
채워진 영역	국가 또는 미국 주 단계구분도	행 개수 또는 컬럼의 합계/평균/최솟값/최댓값; 선형, 로그, 분위수 색상 스케일

인구에 따라 크기가, 대륙에 따라 색상이 정해진 버블

마크에 마우스를 올리면 요약이, 클릭하면 전체 행이 Show in table, Copy as JSON과 함께 표시돼요. 범례 범주를 클릭하면 숨기고, Alt+클릭하면 그 범주만 보여 줘요. 지도 툴바의 테이블 버튼을 누르면 현재 화면의 모든 행을 아래 결과 테이블로 보내요.

주별로 집계한 미국 주문

출발지 → 도착지 라인으로 그린 택시 이동

베이스맵과 내보내기

플러그인에는 오프라인 지도가 포함돼 있어요. OpenStreetMap 데이터로 만든 20 MB 세계 지도라서 인터넷 연결이나 서드파티 타일 서버 없이도 지도가 그려져요. 국가, 지역, 도시, 주요 도로가 들어 있어 국가 단위부터 대도시권 지도까지 커버해요. 거리 수준까지 확대하면 디테일이 부족해지는데, 이때는 상태 표시줄에서 온라인 베이스맵을 제안해요.

베이스맵 목록은 오프라인으로 동작하는 Built in 지도와 타일 서버에서 타일을 내려받는 Online 지도로 나뉘어요. 선택한 지도에는 Offline 또는 Online 표시와 사용하는 서버가 함께 나와요.

Built in: Match app theme(기본값)은 오프라인 지도를 라이트 또는 다크로 표시하고, Country outlines는 가장 단순한 지도예요.
Online: Esri 거리, 지형, 위성 이미지, OpenStreetMap, OpenTopoMap, 또는 임의의 사용자 지정 {z}/{x}/{y} 타일 URL.
PNG(지도와 범례)로 내보내거나, 클립보드로 이미지를 복사하거나, 표시된 행을 GeoJSON으로 저장할 수 있어요.

더 자세한 오프라인 지도

Settings → Basemap의 Detailed area → Load file…을 사용하면 세계 지도 위에 Protomaps 베이스맵 .pmtiles 파일을 추가할 수 있어요. 예를 들어 pmtiles CLI로 만든 특정 도시나 국가의 거리 수준 추출본 같은 파일이요. 파일 범위 밖에서는 평소처럼 세계 지도가 표시돼요.

# street detail for New York City (about 100 MB)
pmtiles extract https://build.protomaps.com/20261014.pmtiles nyc.pmtiles --bbox=-74.26,40.48,-73.69,40.92 --maxzoom=15

최근 빌드 날짜의 파일을 사용하세요. 다른 타일 스키마(OpenMapTiles, 래스터) 파일은 거부돼요.

설정, 쿼리, 뷰포트는 탭과 함께 저장돼요. 복원된 탭은 이전에 실행된 적이 있고 읽기 전용 SELECT 하나일 때만 쿼리를 자동으로 다시 실행해요.

알려진 문제

6.1.5 이하 버전에는 이 플러그인에 영향을 주는 Beekeeper Studio 버그가 3개 있으며, 업스트림 수정이 진행 중이에요:

Community edition에서는 결과 패널이 있는 플러그인 탭(이 플러그인 같은)이 약 150px 높이로만 표시돼요.
쿼리 에디터 컨텍스트 메뉴의 Plot Query on Map이 동작하지 않아요(호스트가 쿼리 텍스트를 전달하지 않아요).
Copy image는 오류로 실패해요. Save as PNG…는 정상 동작해요.

그동안 다른 진입 경로는 정상적으로 사용할 수 있어요.

개발

요구 사항: Beekeeper Studio 5.5+, Node.js 20.19+, Yarn 1.

yarn install
yarn dev        # links the plugin into Beekeeper Studio's plugins folder and hot-reloads
yarn test       # unit tests (vitest)
yarn build      # type-check + production build into dist/

yarn dev는 이 폴더를 플러그인 디렉터리(Linux는 ~/.config/beekeeper-studio/plugins/bk-plugin-map-visualization)에 심볼릭 링크해요. 링크 이름은 manifest.json의 id와 같아야 해요.

src/
  App.vue                 data sources, state, popups, export
  components/             settings panel, legend, icons
  lib/geo/                WKB / WKT / geohash / DMS parsing, regions, offline geocoding
  lib/detect.ts           column auto-detection
  lib/build.ts            rows -> plottable items (CRS, axis order, geocoding)
  lib/model.ts            sizes, colors, aggregates, legends
  lib/renderer.ts         Leaflet layers
  lib/pack.ts             offline map packs: validation, PMTiles source
  lib/offlineMap.ts       bundled world map + detailed area (IndexedDB), shared by all map tabs
  data/                   generated lookup tables (see below)
basemaps/world.pmtiles    the offline world map, bundled into dist/

src/data/의 룩업 테이블은 공개 데이터셋으로 생성돼요:

# download cities15000.zip, countryInfo.txt and admin1CodesASCII.txt from https://download.geonames.org/export/dump/
# and 2023_Gaz_zcta_national.zip from the US Census gazetteer, unzip them into one folder, then:
yarn geodata /path/to/that/folder

basemaps/의 오프라인 세계 지도는 줌 6까지 자른 Protomaps 빌드로, 토지 이용, 토지 피복, POI 레이어를 뺐어요(크기가 약 절반으로 줄고, 데이터 지도에서는 어차피 그리지 않아요):

pmtiles extract https://build.protomaps.com/<YYYYMMDD>.pmtiles world-z6.pmtiles --maxzoom=6
yarn basemap world-z6.pmtiles basemaps/world.pmtiles

플러그인 다운로드 크기를 더 줄여야 한다면 --maxzoom=5로 도시와 도로가 더 적은 5 MB 지도를 만들 수 있어요.

릴리스

bin/make-release.sh를 실행하세요. 기존 태그를 바탕으로 다음 버전을 제안하고, manifest.json과 package.json의 version을 설정한 뒤 커밋하고, v1.0.0 같은 대응 태그를 푸시해요. 릴리스 워크플로가 테스트와 빌드를 거쳐 manifest.json과 플러그인 zip이 포함된 GitHub 릴리스 초안을 만들어요.

데이터 출처와 라이선스

국가와 주 경계는 world-atlas를 통한 Natural Earth와 us-atlas를 통한 US Census 데이터예요(퍼블릭 도메인).
ZIP 코드 중심점은 US Census Bureau ZCTA gazetteer 데이터예요(퍼블릭 도메인).
오프라인 지도는 © OpenStreetMap contributors(ODbL) 및 Natural Earth 데이터로, Protomaps 베이스맵 빌드를 사용하며 protomaps-leaflet(BSD-3-Clause)로 그려요.
지도 타일은 각 서비스(Esri, OpenStreetMap, OpenTopoMap)가 자체 약관에 따라 제공하며, 출처는 지도에 표시돼요.
Leaflet, Leaflet.markercluster, Leaflet.heat로 만들었어요.

이 플러그인은 GPL-3.0 라이선스를 따라요. LICENSE를 참고하세요.

Map Visualization

Readme

설치