koreacoord

Convert between the coordinate systems used on Korean maps — TM, KTM, UTM 52N, Kakao's Congnamul grid, WGS84 and Bessel/Tokyo — with no dependencies.

한국 지도에서 쓰이는 좌표계(TM, KTM, UTM 52N, 카카오 콩나물 좌표, WGS84, 베셀)를 서로 변환합니다. 외부 의존성이 없습니다.

Install

pip install koreacoord

Quick start

from koreacoord import transform

# Seoul City Hall, WGS84 -> Kakao's Congnamul grid
x, y = transform(126.9876757, 37.5611523, "WGS84", "WCONGNAMUL")

# Enum members work too, and are what your IDE will autocomplete
from koreacoord import CoordSystem as CS

x, y = transform(126.9876757, 37.5611523, CS.WGS84, CS.UTM)

The axis order is always x then y — longitude before latitude for geographic systems, easting before northing for projected ones.

Supported systems

from koreacoord import supported_systems

supported_systems()
# ['TM', 'WTM', 'CONGNAMUL', 'WCONGNAMUL', 'KTM', 'WKTM', 'UTM', 'WGS84', 'BESSEL']

Scope

This library is for Korea. Every projection origin and datum parameter is fixed to Korean values:

• UTM is hard-wired to zone 52N (central meridian 129°E). Coordinates from another zone will be silently wrong.
• BESSEL uses the Tokyo-datum shift published for the Korean peninsula, so it is not a general Bessel 1841 conversion.
• CONGNAMUL relocates several island regions (Jeju, Ulleung, Dokdo) the way Kakao's maps draw them. WCONGNAMUL does not — it only applies the 2.5× scale, matching the reference implementation.

Congnamul results are returned as integers; every other system returns floats.

API

transform(x, y, from_system, to_system) -> tuple[float, float]
supported_systems() -> list[str]

transform raises ValueError for an unknown system name and TypeError if the coordinates are not numbers.

The original keyword-only form is kept as an alias:

from koreacoord import get_trans_coord

x, y = get_trans_coord(x=126.9876757, y=37.5611523,
                       input="WGS84", output="WCONGNAMUL")

Accuracy

Measured by the test suite, across seven points from Mokpo to Dokdo:

These are numbers about self-consistency, not about surveying truth. The datum shift is a 7-parameter Molodensky-Badekas approximation, so against official Korean survey data the realistic expectation is metre-level agreement, not centimetres.

한국어

설치

pip install koreacoord

사용법

from koreacoord import transform

# 서울시청, WGS84 -> 카카오 콩나물 좌표
x, y = transform(126.9876757, 37.5611523, "WGS84", "WCONGNAMUL")

# 문자열 대신 열거형을 써도 됩니다 (IDE 자동완성이 됩니다)
from koreacoord import CoordSystem as CS

x, y = transform(126.9876757, 37.5611523, CS.WGS84, CS.UTM)

축 순서는 항상 x 먼저, y 나중입니다. 경위도계는 경도→위도, 평면좌표계는 동거(easting)→북거(northing) 순서입니다.

지원 좌표계

사용 범위

이 라이브러리는 한국 전용입니다. 투영 원점과 측지계 파라미터가 전부 한국 값으로 고정되어 있습니다.

• UTM은 52N 존(중앙자오선 129°E) 으로 고정입니다. 다른 존의 좌표를 넣으면 오류 없이 틀린 값이 나옵니다.
• BESSEL은 한반도용 도쿄측지계 변환값을 쓰므로 일반적인 베셀 1841 변환이 아닙니다.
• CONGNAMUL은 카카오 지도가 제주·울릉·독도를 옮겨 그리는 보정을 반영합니다. WCONGNAMUL은 이 보정 없이 2.5배 배율만 적용합니다 (원 구현과 동일).

콩나물 좌표는 정수로, 나머지는 실수로 반환됩니다.

정확도

목포부터 독도까지 7개 지점으로 측정한 값입니다.

이건 자체 정합성 수치이지 측량 성과와의 일치도가 아닙니다. 측지계 변환이 7-파라미터 Molodensky-Badekas 근사라서, 국토지리정보원 성과와 비교하면 센티미터가 아니라 미터 단위로 맞는다고 보는 게 현실적입니다.

라이선스

MIT