좌표 함수

좌표 함수 (Coordinates)

지구 표면 위의 좌표·거리·변환을 다루는 함수들이에요. 두 점 사이의 거리, 중심각, UTM/MGRS 좌표계 변환, 점이 타원·폴리곤 안에 있는지 확인하는 데 사용해요.

출처: 문서

본문

greatCircleDistance

대원 공식을 사용해 지구 표면 위 두 점 사이의 거리를 계산해요.

greatCircleDistance(lon1Deg, lat1Deg, lon2Deg, lat2Deg)

입력 매개변수 (Input parameters)

lon1Deg — 첫 번째 점의 경도(도). 범위: [-180°, 180°].
lat1Deg — 첫 번째 점의 위도(도). 범위: [-90°, 90°].
lon2Deg — 두 번째 점의 경도(도). 범위: [-180°, 180°].
lat2Deg — 두 번째 점의 위도(도). 범위: [-90°, 90°].

양수 값은 북위·동경에, 음수 값은 남위·서경에 대응해요.

반환 값 (Returned value)

지구 표면 위 두 점 사이의 거리(미터)예요.

입력 매개변수 값이 범위를 벗어나면 예외를 발생시켜요.

예시 (Example)

SELECT greatCircleDistance(55.755831, 37.617673, -55.755831, -37.617673) AS greatCircleDistance

┌─greatCircleDistance─┐
│            14128352 │
└─────────────────────┘

geoDistance

greatCircleDistance와 비슷하지만 구(sphere) 대신 WGS-84 타원체(ellipsoid) 위에서 거리를 계산해요. 지구 지오이드에 더 정밀한 근사예요. 성능은 greatCircleDistance와 동일해요(성능 저하 없음). 지구 위 거리를 계산할 땐 geoDistance를 사용하는 것을 권장해요.

기술 노트: 충분히 가까운 점에 대해서는 좌표 중점에서 접평면의 메트릭을 사용한 평면 근사로 거리를 계산해요.

geoDistance(lon1Deg, lat1Deg, lon2Deg, lat2Deg)

입력 매개변수 (Input parameters)

lon1Deg — 첫 번째 점의 경도(도). 범위: [-180°, 180°].
lat1Deg — 첫 번째 점의 위도(도). 범위: [-90°, 90°].
lon2Deg — 두 번째 점의 경도(도). 범위: [-180°, 180°].
lat2Deg — 두 번째 점의 위도(도). 범위: [-90°, 90°].

양수 값은 북위·동경에, 음수 값은 남위·서경에 대응해요.

반환 값 (Returned value)

지구 표면 위 두 점 사이의 거리(미터)예요.

입력 매개변수 값이 범위를 벗어나면 예외를 발생시켜요.

예시 (Example)

SELECT geoDistance(38.8976, -77.0366, 39.9496, -75.1503) AS geoDistance

┌─geoDistance─┐
│   212458.73 │
└─────────────┘

greatCircleAngle

대원 공식을 사용해 지구 표면 위 두 점 사이의 중심각(central angle)을 계산해요.

greatCircleAngle(lon1Deg, lat1Deg, lon2Deg, lat2Deg)

입력 매개변수 (Input parameters)

lon1Deg — 첫 번째 점의 경도(도).
lat1Deg — 첫 번째 점의 위도(도).
lon2Deg — 두 번째 점의 경도(도).
lat2Deg — 두 번째 점의 위도(도).

반환 값 (Returned value)

두 점 사이의 중심각(도).

예시 (Example)

SELECT greatCircleAngle(0, 0, 45, 0) AS arc

┌─arc─┐
│  45 │
└─────┘

geoToUTM

WGS84 지리 좌표 (longitude, latitude)를 Universal Transverse Mercator (UTM) 좌표로 변환해요.

UTM은 각각 경도 6° 폭의 종대 구역을 덮는 60개의 횡축 메르카토르 투영(transverse Mercator projection) 집합으로, 지리 좌표를 평면 그리드(미터 단위)로 매핑해요. 명시적인 zone이 주어지지 않으면 구역은 경도에서 자동으로 선택되며, 노르웨이와 스발바르에 대한 표준 예외를 적용해요. UTM은 위도 [-80°, 84°] 범위에서만 정의되고, 극지방은 별도의 UPS 시스템을 사용해요.

geoToUTM(longitude, latitude[, zone])

인자 (Arguments)

longitude — 경도(도). 범위: [-180°, 180°]. Float32/Float64.
latitude — 위도(도). 범위: [-80°, 84°]. Float32/Float64.
zone — 선택. 자동 선택 대신 이 UTM 구역으로 투영을 강제해요. 범위: [1, 60]. (U)Int*.

반환 값 (Returned value)

이름 있는 튜플 (easting, northing, zone, band)이에요: easting과 northing은 미터 단위(Float64), UTM zone 번호(UInt8), MGRS 위도 band 문자(FixedString(1)). band가 'N' 이상이면 북반구를 나타내요.

위도가 [-80°, 84°] 밖이거나 경도가 [-180°, 180°] 밖이면 예외를 발생시켜요.

예시 (Example)

SELECT geoToUTM(2.294497, 48.858222) AS utm; -- Eiffel Tower

(448251.5978370684,5411935.125629659,31,'U')

UTMToGeo

UTM 좌표를 다시 WGS84 지리 좌표 (longitude, latitude)로 변환해요. geoToUTM의 역함수예요.

UTMToGeo(easting, northing, zone, is_north)

인자 (Arguments)

easting — 미터 단위의 동향값(500000 m의 false easting 포함). (U)Int*/Float*.
northing — 미터 단위의 북향값(남반구에선 10000000 m의 false northing 포함). (U)Int*/Float*.
zone — UTM 구역 번호. 범위: [1, 60]. (U)Int*.
is_north — 반구: 북반구면 1, 남반구면 0. (U)Int*.

반환 값 (Returned value)

도(degree) 단위의 이름 있는 튜플 (longitude, latitude). Tuple(Float64, Float64).

예시 (Example)

SELECT UTMToGeo(448251.6, 5411935.13, 31, 1) AS coord;

(2.2944970289079203,48.85822204127082)

geoToMGRS

WGS84 지리 좌표 (longitude, latitude)를 Military Grid Reference System (MGRS) 문자열로 인코딩해요.

문자열은 <zone><band><100km square><easting><northing> 형태예요. 예를 들어 31UDQ4825111935. precision 인자는 easting과 northing 각각에 사용되는 자릿수를 제어해요: 5(기본값)는 1 m, 4는 10 m, 3은 100 m, 2는 1 km, 1은 10 km, 0은 100 km 그리드 사각형만. MGRS는 위도 [-80°, 84°] 범위에서만 정의돼요.

geoToMGRS(longitude, latitude[, precision])

인자 (Arguments)

longitude — 경도(도). 범위: [-180°, 180°]. Float32/Float64.
latitude — 위도(도). 범위: [-80°, 84°]. Float32/Float64.
precision — 선택. easting과 northing 각각의 자릿수. 기본값: 5. 범위: [0, 5]. (U)Int*.

반환 값 (Returned value)

MGRS 참조 문자열. String.

예시 (Example)

SELECT geoToMGRS(2.294497, 48.858222) AS mgrs, geoToMGRS(2.294497, 48.858222, 3) AS mgrs_100m;

┌─mgrs────────────┬─mgrs_100m───┐
│ 31UDQ4825111935 │ 31UDQ482119 │
└─────────────────┴─────────────┘

MGRSToGeo

MGRS 문자열을 WGS84 지리 좌표 (longitude, latitude)로 디코딩해요. geoToMGRS의 역함수예요.

반환되는 점은 참조된 그리드 사각형의 중심이므로, 결과의 정밀도는 문자열에 인코딩된 정밀도와 일치해요. 입력의 공백은 무시되고 문자는 대소문자를 구분하지 않아요.

MGRSToGeo(mgrs)

인자 (Arguments)

mgrs — 디코딩할 MGRS 참조 문자열. String/FixedString.

반환 값 (Returned value)

도(degree) 단위의 이름 있는 튜플 (longitude, latitude). Tuple(Float64, Float64).

예시 (Example)

SELECT MGRSToGeo('31UDQ4825111935') AS coord;

(2.294495618908297,48.85822536113692)

pointInEllipses

점이 타원들 중 하나 이상에 속하는지 확인해요. 좌표는 직교 좌표계의 기하 좌표예요.

pointInEllipses(x, y, x₀, y₀, a₀, b₀,...,xₙ, yₙ, aₙ, bₙ)

입력 매개변수 (Input parameters)

x, y — 평면 위 한 점의 좌표.
xᵢ, yᵢ — i번째 타원 중심의 좌표.
aᵢ, bᵢ — i번째 타원의 축(x, y 좌표 단위).

입력 매개변수는 2+4⋅n개여야 해요. 여기서 n은 타원의 개수예요.

반환 값 (Returned values)

점이 타원들 중 하나 이상 안에 있으면 1, 그렇지 않으면 0.

예시 (Example)

SELECT pointInEllipses(10., 10., 10., 9.1, 1., 0.9999)

┌─pointInEllipses(10., 10., 10., 9.1, 1., 0.9999)─┐
│                                               1 │
└─────────────────────────────────────────────────┘

pointInPolygon

평면 위의 점이 폴리곤에 속하는지 확인해요.

pointInPolygon((x, y), [(a, b), (c, d) ...], ...)

입력 값 (Input values)

(x, y) — 평면 위 한 점의 좌표. 데이터 타입 — Tuple — 두 숫자의 튜플, 또는 Point.
[(a, b), (c, d) ...] — 폴리곤 꼭짓점. 데이터 타입 — Array 또는 Ring. 각 꼭짓점은 좌표 쌍 (a, b)로 표현돼요. 꼭짓점은 시계 방향 또는 반시계 방향 순서로 지정해야 해요. 꼭짓점의 최소 개수는 3이에요.
함수는 구멍(잘려 나간 부분)이 있는 폴리곤을 지원해요. 데이터 타입 — Polygon. 전체 Polygon을 두 번째 인자로 넘기거나, 바깥 링을 먼저 넘기고 이어서 각 구멍을 별도의 추가 인자로 넘겨요.
함수는 멀티폴리곤도 지원해요. 데이터 타입 — MultiPolygon. 전체 MultiPolygon을 두 번째 인자로 넘기거나, 각 구성 폴리곤을 자신만의 인자로 나열해요.
폴리곤 인자는 폴리곤 형태의 값을 담는 Geometry 컬럼(Ring, Polygon, MultiPolygon)일 수도 있어요.

폴리곤 형태 타입(Ring, Polygon, MultiPolygon, Geometry)은 상수(constant) 또는 일반(비상수) 테이블 컬럼으로 전달할 수 있어요. 폴리곤을 여러 개의 별도 인자(바깥 링 다음에 구멍들, 또는 멀티폴리곤의 여러 폴리곤)로 제공할 때는 그 모든 인자가 상수여야 해요.

반환 값 (Returned values)

점이 폴리곤 안에 있으면 1, 그렇지 않으면 0. 점이 폴리곤 경계 위에 있으면 함수가 0 또는 1을 반환할 수 있어요.

예시 (Example)

SELECT pointInPolygon((3., 3.), [(6, 0), (8, 4), (5, 8), (0, 2)]) AS res

┌─res─┐
│   1 │
└─────┘

폴리곤은 이름 있는 기하 데이터 타입으로도 줄 수 있고, 테이블 컬럼으로도 줄 수 있어요:

CREATE TABLE poly (id UInt32, shape Polygon) ENGINE = Memory;
INSERT INTO poly VALUES (1, [[(0, 0), (10, 0), (10, 10), (0, 10)], [(4, 4), (6, 4), (6, 6), (4, 6)]]);
SELECT id, pointInPolygon((2., 2.), shape) AS res FROM poly;

┌─id─┬─res─┐
│  1 │   1 │
└────┴─────┘

참고

• 기하 검증을 우회하려면 validate_polygons = 0을 설정할 수 있어요.

• pointInPolygon은 모든 폴리곤이 잘 형성되었다고 가정해요. 입력이 자기 교차하거나, 링 순서가 잘못되었거나, 모서리가 겹치면 결과가 신뢰할 수 없게 돼요. 특히 점이 정확히 모서리·꼭짓점 위에 있거나, "안/밖" 개념이 정의되지 않는 자기 교차 지점 안에 있을 때 그래요. • 폴리곤 인자가 상수이고 점이 인덱스 키 컬럼으로 표현될 때(x, y가 PRIMARY KEY의 일부이거나 minmax 인덱스로 커버되는 테이블에서 pointInPolygon((x, y), constant_polygon) 같은 경우), ClickHouse는 기본 키와 minmax 데이터 스킵 인덱스 둘 다 사용해 관련 없는 granule을 제거할 수 있어요.

더 알아보기 (Learn more)

ClickHouse 함수 목록 전체는 함수 개요를 참고해요.