MapConductor문서 / 기본 / Raster Layer
래스터 레이어
XYZ 타일의 URL 템플릿을 지정해, 임의의 타일셋을 지도에 겹칩니다. 지리원 타일 같은 외부 타일을 그대로 쓸 수 있습니다.
ANDROID
com.mapconductor:core
iOS
MapConductorCore
REACT
@mapconductor/js-sdk-react
01 · 사용법
소스에 URL 템플릿을 넘기기만 하면 됩니다. 투명도나 줌 범위는 레이어 쪽에서 제어합니다.
RasterLayerScreen.kt · Jetpack Compose
val rasterLayerState = RasterLayerState(
id = "gsi-raster",
source = RasterLayerSource.UrlTemplate(
template = "https://cyberjapandata.gsi.go.jp/xyz/relief/{z}/{x}/{y}.png",
tileSize = 256,
minZoom = 5,
maxZoom = 15,
),
opacity = 0.75f,
)
MapLibreMapView(state = mapState) {
RasterLayer(rasterLayerState)
}RasterLayerView.swift · SwiftUI
@StateObject private var layerState = RasterLayerState(
source: .urlTemplate(
template: "https://cyberjapandata.gsi.go.jp/xyz/relief/{z}/{x}/{y}.png",
tileSize: 256,
minZoom: 5,
maxZoom: 15
),
opacity: 0.75,
id: "gsi-raster"
)
MapLibreMapView(state: mapState) {
RasterLayer(state: layerState)
}RasterLayerPage.tsx · React
import { RasterLayerSource, createRasterLayerState } from '@mapconductor/js-sdk-core';
import { RasterLayer } from '@mapconductor/js-sdk-react';
const state = useMemo(() => createRasterLayerState({
id: 'gsi-raster',
source: RasterLayerSource.UrlTemplate({
template: 'https://cyberjapandata.gsi.go.jp/xyz/relief/{z}/{x}/{y}.png',
tileSize: 256,
minZoom: 5,
maxZoom: 15,
attributionRules: [...GSI_RELIEF_ATTRIBUTION_RULES],
}),
opacity,
}), [opacity]);
<RasterLayer state={state} />02 · 주요 옵션
Option
Default
설명
template
—
{z}/{x}/{y}를 포함하는 타일의 URL 템플릿.
tileSize
512
타일의 한 변의 픽셀 수.
minZoom / maxZoom
없음
레이어를 표시할 줌 범위. 지정하지 않으면 모든 줌에서 표시합니다.
attributionRules
[]
줌이나 범위에 따른 출처 표기의 규칙. source에 지정합니다.
opacity
1.0
레이어 전체의 불투명도(레이어 쪽 지정).
visible
true
표시・비표시의 전환.
zIndex
0
다른 레이어와의 겹침 순서.
userAgent
MapConductor/…
타일 취득 시의 User-Agent. 지원 상황은 프로바이더에 따라 다릅니다(아래 표).
extraHeaders
없음
타일 취득 시에 붙이는 추가 헤더. 인증 토큰 등. 지원 상황은 프로바이더에 따라 다릅니다(아래 표).
03 · 헤더의 지원 상황
타일을 가지러 가는 것은 각 프로바이더의 지도 SDK이며, 요청을 바꿔 쓸 수 있는 창구가 있는지는 SDK마다 다릅니다. 창구가 없는 프로바이더에서는 지정이 무시되고, 실행 시에 로그가 나옵니다. 아래 표는 타일 요청을 실제로 받아 확인한 결과입니다(네이티브는 실기, Web은 브라우저).
Web에서는 userAgent가 어느 프로바이더에서도 듣지 않습니다. 브라우저가 User-Agent의 덮어쓰기를 금지하고 있기 때문이며, SDK 쪽에서 우회할 방법은 없습니다. 프로퍼티 자체는 React Native를 위해 남겨 두었고, RN에서는 네이티브 SDK로 값이 전달되어 실제로 듣습니다. 같은 코드를 Web과 RN 양쪽에서 돌릴 수 있게 하기 위한 의도적인 설계입니다.
Provider
iOS
Android
Web(extraHeaders)
비고
MapLibre
✓
✓
✓
iOS는 MLNNetworkConfiguration, Android는 OkHttp 클라이언트의 교체, Web은 maplibre-gl의 transformRequest 경유. 어느 쪽이든 타일 배포 호스트로 가는 요청에만 붙습니다.
MapTiler
✓
—
✓
iOS는 MapLibre와 같은 구조입니다. Android의 MapTiler SDK는 WebView 위에서 동작하기 때문에, 네이티브 쪽에서 헤더를 바꿔 넣을 수 없습니다.
MapKit
✓
—
—
iOS 전용 프로바이더입니다.
HERE
✓
✓
—
iOS는 헤더 지정이 있을 때만 로컬 프록시를 경유합니다(1홉 늘어납니다).
Google Maps
userAgent
✓
—
Android는 자체적으로 타일을 취득하기 때문에 양쪽 다 쓸 수 있습니다. iOS의 GMSURLTileLayer는 userAgent만 공개하고 있어 extraHeaders는 무시됩니다.
Mapbox
—
—
✓
iOS / Android의 SDK에는 요청을 바꿔 쓰는 공개 API가 없습니다. Web의 mapbox-gl에는 transformRequest가 있기 때문에 Web만 지원합니다.
ArcGIS
—
—
—
위와 같음.
TomTom
—
—
—
위와 같음.
Longdo
—
—
—
위와 같음.
Leaflet
—
—
✓
Web 전용. 헤더 지정이 있을 때만 fetch로 타일을 가져와 blob으로 바꿔 넣습니다.
OpenLayers
—
—
✓
Web 전용. 위와 같음(tileLoadFunction을 교체).
Azure Maps
—
—
✓
Web 전용. transformRequest 경유.
Cesium
—
—
✓(미계측)
Web 전용. headers를 가진 Resource를 넘기는 구현이지만, 샘플 앱 쪽의 다른 결함 때문에 실측하지 못했습니다.
헤더가 필수인 타일 서버를 쓰는 경우에는, 지원하는 프로바이더를 골라 주세요. 미지원 프로바이더에서도, URL의 쿼리 파라미터에 토큰을 싣는 방식이라면 이용할 수 있습니다.
04 · 샘플
지리원 타일의 예
샘플에서는 음영 기복도와 표준 지도를 전환하고, 투명도를 슬라이더로 바꿉니다. 출처 표기는 attributionRules로 자동으로 전환됩니다.
영상으로 보여 주는 구현 · Android + MapLibreKotlin · Jetpack Compose
var opacity by remember { mutableFloatStateOf(0.75f) }
var relief by remember { mutableStateOf(true) }
val layerState = remember { RasterLayerState(id = "gsi-raster") }
// Both source and opacity can be reassigned; the layer is not rebuilt
LaunchedEffect(relief, opacity) {
layerState.source = RasterLayerSource.UrlTemplate(
template = if (relief) {
"https://cyberjapandata.gsi.go.jp/xyz/relief/{z}/{x}/{y}.png"
} else {
"https://cyberjapandata.gsi.go.jp/xyz/std/{z}/{x}/{y}.png"
},
tileSize = 256,
minZoom = 5,
maxZoom = 15,
)
layerState.opacity = opacity
}
MapLibreMapView(state = mapViewState) {
RasterLayer(layerState)
}
Slider(value = opacity, onValueChange = { opacity = it })
Switch(checked = relief, onCheckedChange = { relief = it })영상 미촬영외부의 타일 서버를 겹치고, 줌에 맞춰 타일이 바뀌어 가는 모습.