class
MapView
implements IView
Unified map view with 2D/3D mode switching. Creates a WebGPU canvas, manages layers, handles user interaction, and provides coordinate conversion. This is the main entry point for the library.
Constructor
new MapView(options: MapViewOptions) | Parameter | Type | Description | |
|---|---|---|---|
options | MapViewOptions | required | View configuration |
MapViewOptions
| Field | Type | Description | |
|---|---|---|---|
container | HTMLElement | string | null | required | DOM element or CSS selector for the map container |
mode | '2d' | '3d' | optional | Initial rendering mode Default: '2d' |
center | [number, number] | optional | Initial center as [longitude, latitude] Default: [0, 0] |
zoom | number | optional | Initial zoom level Default: 2 |
rotation | number | optional | Initial rotation in degrees (2D only) Default: 0 |
pitch | number | optional | Initial pitch in degrees (3D only) Default: 0 |
bearing | number | optional | Initial bearing in degrees (3D only) Default: 0 |
minZoom | number | optional | Minimum allowed zoom level Default: 0 |
maxZoom | number | optional | Maximum allowed zoom level Default: 22 |
renderEngine | IRenderEngine | optional | WebGPU render engine instance (e.g. new RenderEngine()) |
backgroundColor | string | optional | Canvas background color Default: 'black' |
interaction | InteractionHandlerOptions | GlobeInteractionOptions | false | optional | Interaction config, or false to disable |
Properties
| Name | Type | Access | Description |
|---|---|---|---|
id | string | readonly | Unique view identifier |
type | '2d' | '3d' | readonly | Active rendering mode |
map | GameMap | readonly | Layer collection (add/remove/reorder layers here) |
canvas | HTMLCanvasElement | null | readonly | WebGPU canvas element |
center | [number, number] | readonly | Current center [longitude, latitude] |
zoom | number | readonly | Current zoom level |
pitch | number | readonly | Current pitch in degrees |
bearing | number | readonly | Current bearing in degrees |
rotation | number | readonly | Current rotation in degrees (2D only) |
mode | '2d' | '3d' | readonly | Active mode string |
ready | boolean | readonly | True when GPU + canvas initialized |
gpuReady | boolean | readonly | True when WebGPU device ready |
toolManager | ToolManager | readonly | Tool manager (lazy-initialized on first access) |
Methods
switchTo()
switchTo(mode: '2d' | '3d'): Promise<void> Switch between 2D flat map and 3D globe mode. Preserves center/zoom.
| Parameter | Type | Description | |
|---|---|---|---|
mode | '2d' | '3d' | required | Target mode |
Returns
Promise<void> goTo()
goTo(target: GoToTarget): Promise<void> Animated navigation to a target view state.
| Parameter | Type | Description | |
|---|---|---|---|
target | GoToTarget | required | { center?, zoom?, pitch?, bearing?, rotation?, duration? } |
Returns
Promise<void> toMap()
toMap(screenX: number, screenY: number): [number, number] | null Convert screen pixel coordinates to geographic [lon, lat].
Returns
[number, number] | null toScreen()
toScreen(lon: number, lat: number): [number, number] | null Convert geographic coordinates to screen pixels.
Returns
[number, number] | null hitTest()
hitTest(screenX: number, screenY: number): Promise<HitTestResult[]> Query features at a screen position using GPU picking.
Returns
Promise<HitTestResult[]> when()
when(): Promise<void> Promise that resolves when the map is fully initialized (GPU + canvas ready).
Returns
Promise<void> on()
on<K extends keyof MapViewEvents>(event: K, handler: (data: MapViewEvents[K]) => void): void Register an event listener.
Returns
void off()
off<K extends keyof MapViewEvents>(event: K, handler: (data: MapViewEvents[K]) => void): void Remove an event listener.
Returns
void loadIcon()
loadIcon(id: string, source: string | ImageBitmap): Promise<void> Load an icon image for use with PointSymbol type="icon".
Returns
Promise<void> loadSvgIcon()
loadSvgIcon(id: string, svgMarkup: string, width: number, height: number): Promise<void> Load an SVG string as an icon.
Returns
Promise<void> loadModel()
loadModel(id: string, source: string | ArrayBuffer): Promise<void> Load a GLTF/GLB 3D model for use with ModelSymbol.
Returns
Promise<void> getBounds()
getBounds(): Extent | null Get the current visible extent as an Extent.
Returns
Extent | null getViewState()
getViewState(): ViewState Get the full view state (center, zoom, pitch, bearing, rotation).
Returns
ViewState setHeightExaggeration()
setHeightExaggeration(factor: number): void Set terrain height exaggeration factor.
Returns
void destroy()
destroy(): void Release all GPU resources, detach canvas, stop render loop.
Returns
void Events
| Event | Payload | Description |
|---|---|---|
'view-change' | { center, zoom, pitch, bearing, rotation, mode } | Fires on any camera/view state change |
'mode-change' | { from: '2d'|'3d', to: '2d'|'3d' } | Fires when switching between 2D and 3D |
'ready' | void | Fires when GPU + canvas fully initialized |
'error' | MapError | Fires on any error (GPU lost, shader compile, etc.) |
'layer-add' | { layer: ILayer } | Fires when a layer is added to the map |
'layer-remove' | { layer: ILayer } | Fires when a layer is removed |
'click' | { screenX, screenY, mapPoint } | Fires on map click |
'pointer-move' | { screenX, screenY, mapPoint } | Fires on pointer move over the map |
'frame' | { frameNumber, fps } | Fires every rendered frame |
'destroy' | void | Fires when the view is destroyed |
Example
import { MapView } from '@mapgpu/core';
import { RenderEngine } from '@mapgpu/render-webgpu';
import { RasterTileLayer } from '@mapgpu/layers';
const view = new MapView({
container: '#map',
center: [28.97, 41.01],
zoom: 10,
renderEngine: new RenderEngine(),
});
view.map.add(new RasterTileLayer({
id: 'osm',
urlTemplate: 'https://tile.openstreetmap.org/{z}/{x}/{y}.png',
}));
await view.when();
console.log('Map ready!');