Map, layers, and camera

Generated from the same registry as the Chinese reference. Contract version: 0.5-session. Edit the registry and reviewed English catalog, then rerun script_contract; do not edit this file. See the script guide.

Platform labels below are registry declarations, not device acceptance. Consult the platform coverage guide for actual host coverage and limits. These are the existing gis compatibility-module APIs; the shared sqsmap map facade is documented separately.

map.sources

`map.sources.cluster`

Build stable hierarchical point clusters in the background; aggregate after filtering.

Permission: map.write
Declared platforms: desktop, mobile, web
Signature: map.sources.cluster(arg0: string, arg1: SourceRef, arg2: ClusterOptions, arg3: SceneOwnerOptions): Operation<SourceRef>

`map.sources.createTransient`

Create a scene-owned, read-only live point source without changing the original file.

Permission: map.write
Declared platforms: desktop, mobile, web
Signature: map.sources.createTransient(arg0: TransientSourceOptions, arg1: SceneOwnerOptions): Operation<SourceRef>

map.camera

`map.camera.easeTo`

Prepare a scene-owned 2D camera animation; user camera navigation can interrupt it.

Permission: map.write
Declared platforms: desktop, mobile, web
Signature: map.camera.easeTo(arg0: CameraMotionOptions, arg1: SceneOwnerOptions): Operation<PlaybackRef>

`map.camera.flyTo`

Prepare a scene-owned 2D camera flight; user camera navigation can interrupt it.

Permission: map.write
Declared platforms: desktop, mobile, web
Signature: map.camera.flyTo(arg0: CameraMotionOptions, arg1: SceneOwnerOptions): Operation<PlaybackRef>

map.contours

`map.contours.enable`

Enable 2D Terrain-RGB contour rendering.

Permission: map.write
Declared platforms: desktop, mobile, web
Signature: map.contours.enable(arg0: ContourOptions): Operation<ContourStatus>

`map.contours.disable`

Disable 2D Terrain-RGB contour rendering.

Permission: map.write
Declared platforms: desktop, mobile, web
Signature: map.contours.disable(): Operation<ContourStatus>

`map.contours.status`

Read 2D Terrain-RGB contour loading status.

Permission: map.write
Declared platforms: desktop, mobile, web
Signature: map.contours.status(): Operation<ContourStatus>

`map.contours.sampleElevation`

Sample elevation at a WGS84 point from the current Terrain-RGB source; transparent pixels mean missing data.

Permission: project.read
Declared platforms: desktop, mobile, web
Signature: map.contours.sampleElevation(arg0: [number,number]): Operation<OnlineElevationSample>

`map.contours.snapshot`

Read a frozen contour vector dataset for a bounds rectangle, with elevation_m in meters; do not read screen caches or change the display.

Permission: project.read
Declared platforms: desktop, mobile, web
Signature: map.contours.snapshot(arg0?: ContourSnapshotOptions): Operation<ContourSnapshot>

map.basemap

`map.basemap.load`

Load a style basemap and return a cancellable task with a readiness wait.

Permission: map.write
Declared platforms: desktop, mobile, web
Signature: map.basemap.load(arg0: BasemapLoadOptions): Operation<BasemapLoadRef>

map.contours

`map.contours.profileLines`

Read parallel terrain profiles within bounds, preserving meter elevations at each vertex; return frozen 3D lines without changing the display.

Permission: project.read
Declared platforms: desktop, mobile, web
Signature: map.contours.profileLines(arg0?: TerrainProfileOptions): Operation<TerrainProfileSnapshot>

map.basemap

`map.basemap.ready`

Wait for the initial visible basemap commit and return its status.

Permission: project.read
Declared platforms: desktop, mobile, web
Signature: map.basemap.ready(arg0: BasemapLoadRef): Operation<BasemapStatus>

`map.basemap.cancel`

Cancel a basemap load that has not yet committed.

Permission: map.write
Declared platforms: desktop, mobile, web
Signature: map.basemap.cancel(arg0: BasemapLoadRef): Operation<void>

`map.basemap.status`

Read current basemap loading status.

Permission: project.read
Declared platforms: desktop, mobile, web
Signature: map.basemap.status(): Operation<BasemapStatus>

map

`map.open`

Read a vector file and display polygons, lines, or circles; requires project.read and map.write.

Permission: map.write
Declared platforms: desktop, mobile
Signature: map.open(arg0: string, arg1?: MapOpenOptions): Operation<MapLayerRef>

`map.getStyle`

Read the current shared inline style snapshot including source data and layer edits without modifying the map

Permission: project.read
Declared platforms: desktop, web
Signature: map.getStyle(): Operation<import("sqsmap").StyleSpecification>

`map.setStyle`

Atomically apply an HTTP or custom-protocol style URL or inline style. Omitted diff or true preserves compatible sources and layers; false fully replaces, and null clears. Flush confirms writes, not resource readiness.

Permission: map.write
Declared platforms: desktop, web
Signature: map.setStyle(arg0: string | null | import("sqsmap").StyleSpecification, arg1?: import("sqsmap").StyleOptions): Operation<void>

`map.getAttributions`

Read complete plain-text logical source credits with source and layer provenance, without changing the map.

Permission: project.read
Declared platforms: desktop, web
Signature: map.getAttributions(): Operation<import("sqsmap").AttributionSnapshot>

map.lifecycle

`map.lifecycle.read`

Read initialization, first complete drawing, actual frames and pending work without sampling animations or advancing rendering.

Permission: project.read
Declared platforms: desktop, web
Signature: map.lifecycle.read(arg0: string, arg1: unknown[]): Operation<unknown>

map

`map.getCapabilities`

Read implemented shared map capabilities; missing or false means unavailable.

Permission: project.read
Declared platforms: desktop, web
Signature: map.getCapabilities(): Operation<Readonly<Record<string, unknown>>>

map.protocol

`map.protocol.write`

Register or remove a protocol handler owned by the current desktop or web script; callbacks and binary replies use a bounded private channel, and stopping releases only its own registrations.

Permission: map.write
Declared platforms: desktop, web
Signature: map.protocol.write(arg0: string, arg1: [string, number]): Operation<unknown>

map.resourcePolicy

`map.resourcePolicy.read`

Read shared resource configuration snapshots and plan HTTP or custom-protocol requests. Hosts deliver resources.

Permission: project.read
Declared platforms: desktop, web
Signature: map.resourcePolicy.read(arg0: string, arg1: unknown[]): Operation<unknown>

`map.resourcePolicy.write`

Replace shared resource configuration used for HTTP and custom-protocol plans. Hosts deliver resources.

Permission: map.write
Declared platforms: desktop, web
Signature: map.resourcePolicy.write(arg0: string, arg1: unknown[]): Operation<unknown>

map.scene

`map.scene.read`

Shared scene lifecycle, clock, GeoJSON ownership, map-owned route playback, planar line animation and color, opacity and width tracks.

Permission: project.read
Declared platforms: desktop, web
Signature: map.scene.read(arg0: string, arg1: unknown[]): Operation<unknown>

`map.scene.write`

Shared scene lifecycle, clock, GeoJSON ownership, map-owned route playback, planar line animation and color, opacity and width tracks.

Permission: map.write
Declared platforms: desktop, web
Signature: map.scene.write(arg0: string, arg1: unknown[]): Operation<unknown>

map.source

`map.source.read`

Read shared GeoJSON or georeferenced media source identity, loading/media state, live protocol or independent snapshots; await queries. Read shared tiled-source metadata. sqs.getMaterialFadeDuration takes no arguments and returns the integer-zoom material fade duration in milliseconds, default 300. sqs.getLabelFadeDuration takes no arguments and returns the independent label placement fade duration in milliseconds, default 300.

Permission: project.read
Declared platforms: desktop, web
Signature: map.source.read(arg0: string, arg1: unknown[]): Operation<unknown>

`map.source.write`

Register, remove or atomically update shared GeoJSON/tiled/media sources. GeoJSON, TileJSON, image and MP4/H.264 source URLs support HTTP or validated custom protocols; encoded resource delivery is host-owned. Also supports decoded frames, named Canvas RGBA frames and playback, shared raster layers, MVT circle/line/fill queries and source-layer feature-state. Does not create display layers automatically. sqs.setMaterialFadeDuration accepts one finite, nonnegative value up to 3600000 milliseconds, preserving source identities, caches and clock; it does not change manual pattern or dash timing. sqs.setLabelFadeDuration accepts one finite, nonnegative value up to 3600000 milliseconds, independently controls label placement fades (0 is immediate), and preserves source identities, caches and clock.

Permission: map.write
Declared platforms: desktop, web
Signature: map.source.write(arg0: string, arg1: unknown[]): Operation<unknown>

map.glyph

`map.glyph.read`

Read the parsed style glyph service URL; await authoritative queries.

Permission: project.read
Declared platforms: desktop, web
Signature: map.glyph.read(arg0: string, arg1: unknown[]): Operation<unknown>

`map.glyph.write`

Replace or clear an HTTP or custom-protocol glyph service, retaining loaded sources and images and cancelling old requests

Permission: map.write
Declared platforms: desktop, web
Signature: map.glyph.write(arg0: string, arg1: unknown[]): Operation<unknown>

map.image

`map.image.load`

Load HTTP or custom-protocol PNG/JPEG/WebP images into independent RGBA8 pixels; do not register automatically

Permission: project.read
Declared platforms: desktop, web
Signature: map.image.load(arg0: string): Operation<unknown>

`map.image.read`

Read style and runtime images; return independent RGBA pixels and optional stretch, content rectangle and text-fit metadata copies.

Permission: project.read
Declared platforms: desktop, web
Signature: map.image.read(arg0: string, arg1: unknown[]): Operation<unknown>

`map.image.write`

Add, update or remove shared static and dynamic images; bounded callbacks, repaint and same-size updates reuse checked image candidates and metadata.

Permission: map.write
Declared platforms: desktop, web
Signature: map.image.write(arg0: string, arg1: unknown[]): Operation<unknown>

map.layer

`map.layer.read`

Read shared GeoJSON or media raster layers, properties, filters and UI metadata; await queries.

Permission: project.read
Declared platforms: desktop, web
Signature: map.layer.read(arg0: string, arg1: unknown[]): Operation<unknown>

`map.layer.write`

Add, remove, reorder and style common circle/line/fill/raster,default/multiple-algorithm map/viewport hillshade and color-relief elevation layers,planar/perspective fill-extrusion buildings,planar heatmap,point image/bundled-font text with configurable typography symbols with SDF recoloring/missing-image events/default collision placement and source-less background layers with zoom ranges. Feature layers support filters; media has no features. Camera and source identity are preserved.

Permission: map.write
Declared platforms: desktop, web
Signature: map.layer.write(arg0: string, arg1: unknown[]): Operation<unknown>

map.camera

`map.camera.read`

Read the authoritative planar or spherical camera through the common map facade; await queries.

Permission: project.read
Declared platforms: desktop, web
Signature: map.camera.read(arg0: string, arg1: unknown[]): Operation<unknown>

`map.camera.write`

Apply validated planar or spherical camera commands through the common facade; confirm with flush. Globe animation, bounds fitting, roll and persistent padding are connected; padding keeps the geographic pose and shifts the projection principal point.

Permission: map.write
Declared platforms: desktop, web
Signature: map.camera.write(arg0: string, arg1: unknown[]): Operation<unknown>

map.light

`map.light.read`

Read shared constant lighting and historical configuration; await queries.

Permission: project.read
Declared platforms: desktop, web
Signature: map.light.read(arg0: string, arg1: unknown[]): Operation<unknown>

`map.light.write`

Atomically set shared light color, direction, and intensity; confirm writes with flush.

Permission: map.write
Declared platforms: desktop, web
Signature: map.light.write(arg0: string, arg1: unknown[]): Operation<unknown>

map.gesture

`map.gesture.read`

Read shared navigation switches and recognized physical input activity; await authoritative queries.

Permission: project.read
Declared platforms: desktop, web
Signature: map.gesture.read(arg0: string, arg1: unknown[]): Operation<unknown>

`map.gesture.write`

Set shared default navigation switches and await application confirmation.

Permission: map.write
Declared platforms: desktop, web
Signature: map.gesture.write(arg0: string, arg1: unknown[]): Operation<unknown>

map

`map.flush`

Confirm map operations submitted before this call; optionally wait for actual rendering. This does not imply source readiness.

Permission: project.read
Declared platforms: desktop, mobile, web
Signature: map.flush(arg0?: import("sqsmap").FlushOptions): Operation<import("sqsmap").MapCommitResult>

`map.state`

Read current loading, layer, and task summaries.

Permission: project.read
Declared platforms: desktop, mobile, web
Signature: map.state(): Operation<MapStateSnapshot>

`map.setLocale`

Set map-control and context-menu language; auto follows the browser language preference. Return the resolved language.

Permission: map.write
Declared platforms: web
Signature: map.setLocale(arg0: 'auto' | 'zh' | 'en'): Operation<'zh' | 'en'>

`map.getLocale`

Read the resolved language of map controls and context menus.

Permission: project.read
Declared platforms: web
Signature: map.getLocale(): Operation<'zh' | 'en'>

`map.clear`

Preview clearing display layers and script sources; applying requires host confirmation.

Permission: map.write
Declared platforms: desktop, mobile, web
Signature: map.clear(): ChangePlan<void>

`map.addGeoJSON`

Read GeoJSON and display its geometry; requires project.read and map.write.

Permission: map.write
Declared platforms: desktop, mobile, web
Signature: map.addGeoJSON(arg0: string, arg1: GeoJSON): Operation<MapLayerRef>

map.sources

`map.sources.add`

Permission: map.write
Declared platforms: desktop, mobile, web
Signature: map.sources.add(arg0: string, arg1: DatasetSourceSpec | GeoJSONSourceSpec | VectorFileSourceSpec | RasterFileSourceSpec | XyzSourceSpec | RasterDemSourceSpec | OnlineRasterDemSourceSpec | PointCloudSourceSpec | ModelSourceSpec | Tiles3dSourceSpec | GaussianSplatSourceSpec, arg2?: SceneOwnerOptions): Operation<SourceRef>

`map.sources.get`

Look up a map source by its exact ID.

Permission: project.read
Declared platforms: desktop, mobile, web
Signature: map.sources.get(arg0: string): Operation<SourceRef | null>

`map.sources.remove`

Preview removal of a source that has no dependent display layers.

Permission: map.write
Declared platforms: desktop, mobile, web
Signature: map.sources.remove(arg0: SourceRef): ChangePlan<void>

`map.sources.list`

List current map sources.

Permission: project.read
Declared platforms: desktop, mobile, web
Signature: map.sources.list(arg0?: PageOptions): Operation<Page<SourceInfo>>

map.layers

`map.layers.add`

Create a display layer from an existing source: fill, line, circle, raster, hillshade, color relief, point cloud, model, 3D Tiles, or Gaussian splats.

Permission: map.write
Declared platforms: desktop, mobile, web
Signature: map.layers.add(arg0: FillLineLayerSpec | RasterLayerSpec | SymbolLayerSpec | HeatmapLayerSpec | HillshadeLayerSpec | ColorReliefLayerSpec | PointCloudLayerSpec | ModelLayerSpec | Tiles3dLayerSpec | GaussianSplatLayerSpec, arg1?: SceneOwnerOptions): Operation<MapLayerRef>

`map.layers.get`

Look up a display layer by its exact ID or name.

Permission: project.read
Declared platforms: desktop, mobile, web
Signature: map.layers.get(arg0: string): Operation<MapLayerRef | null>

`map.layers.removeMany`

Preview and confirm removing multiple display layers together; original files remain.

Permission: map.write
Declared platforms: desktop, mobile, web
Signature: map.layers.removeMany(arg0: MapLayerRef[]): ChangePlan<void>

`map.layers.remove`

Preview removing one display layer.

Permission: map.write
Declared platforms: desktop, mobile, web
Signature: map.layers.remove(arg0: MapLayerRef): ChangePlan<void>

`map.layers.rename`

Change the display-layer name.

Permission: map.write
Declared platforms: desktop, mobile, web
Signature: map.layers.rename(arg0: MapLayerRef, arg1: string): Operation<void>

`map.layers.move`

Change display-layer stacking order.

Permission: map.write
Declared platforms: desktop, mobile, web
Signature: map.layers.move(arg0: MapLayerRef, arg1: MapLayerMoveOptions): Operation<void>

`map.layers.duplicate`

Copy display configuration and reuse the original source.

Permission: map.write
Declared platforms: desktop, mobile, web
Signature: map.layers.duplicate(arg0: MapLayerRef, arg1?: MapLayerDuplicateOptions): Operation<MapLayerRef>

`map.layers.list`

Page through script-managed and existing workbench vector/raster layer summaries.

Permission: project.read
Declared platforms: desktop, mobile, web
Signature: map.layers.list(arg0?: PageOptions): Operation<Page<MapLayerInfo>>

`map.layers.setVisible`

Set display-layer visibility.

Permission: map.write
Declared platforms: desktop, mobile, web
Signature: map.layers.setVisible(arg0: MapLayerRef, arg1: boolean): Operation<void>

`map.layers.setOpacity`

Set the opacity multiplier for the whole layer.

Permission: map.write
Declared platforms: desktop, mobile, web
Signature: map.layers.setOpacity(arg0: MapLayerRef, arg1: number): Operation<void>

`map.layers.setPaint`

Atomically update constant, property-driven, and continuous-zoom paint styles.

Permission: map.write
Declared platforms: desktop, mobile, web
Signature: map.layers.setPaint(arg0: MapLayerRef, arg1: FillLinePaintPatch | SymbolPaintPatch | HeatmapPaint | ElevationPaintPatch | PointCloudPaint | Tiles3dPaint): Operation<void>

`map.layers.setHeight`

Set static line display heights from a numeric field: meters=(value-base)*exaggeration+offset. This is a flat datum, not terrain draping. Only static solid lines in EPSG:3857 are supported; validate the entire field before applying. Pass null to restore default height.

Permission: map.write
Declared platforms: desktop, mobile, web
Signature: map.layers.setHeight(arg0: MapLayerRef, arg1: LayerHeightOptions | null): Operation<LayerHeightSummary>

`map.layers.classify`

Generate deterministic classification colors and a legend from the complete source.

Permission: map.write
Declared platforms: desktop, mobile, web
Signature: map.layers.classify(arg0: MapLayerRef, arg1: ClassificationOptions): Operation<ClassificationSummary>

`map.layers.setVertexHeight`

Set line display height from each vertex's meter elevation without changing source geometry. Supports Web Mercator static solid lines; validate before applying. The source is read-only while displayed; null clears heights.

Permission: map.write
Declared platforms: desktop, mobile, web
Signature: map.layers.setVertexHeight(arg0: MapLayerRef, arg1?: VertexHeightOptions | null): Operation<VertexHeightSummary>

`map.layers.clearClassification`

Clear classification and restore the prior color style.

Permission: map.write
Declared platforms: desktop, mobile, web
Signature: map.layers.clearClassification(arg0: MapLayerRef): Operation<void>

`map.layers.legend`

Page through the full classification legend and known business-code meanings.

Permission: project.read
Declared platforms: desktop, mobile, web
Signature: map.layers.legend(arg0: MapLayerRef, arg1?: PageOptions): Operation<Page<LegendEntry>>

`map.layers.ready`

Wait for layer loading in the current viewport; this does not load the entire dataset. A deadline returns current status.

Permission: project.read
Declared platforms: desktop, mobile, web
Signature: map.layers.ready(arg0: MapLayerRef, arg1?: LayerReadyOptions): Operation<MapLayerInfo>

`map.layers.setFilter`

Filter displayed features using typed conditions without changing source data.

Permission: map.write
Declared platforms: desktop, mobile, web
Signature: map.layers.setFilter(arg0: MapLayerRef, arg1: Expression|boolean|null): Operation<void>

map.camera

`map.camera.fitLayer`

Fit the camera to the specified display layer's bounds.

Permission: map.write
Declared platforms: desktop, mobile, web
Signature: map.camera.fitLayer(arg0: MapLayerRef, arg1?: CameraFitOptions): Operation<void>

`map.camera.fitLayers`

Fit the camera to the combined bounds of specified display layers.

Permission: map.write
Declared platforms: desktop, mobile, web
Signature: map.camera.fitLayers(arg0: MapLayerRef[], arg1?: CameraFitOptions): Operation<void>

`map.camera.fitFeature`

Fit the camera to one actual feature acquired in this task.

Permission: map.write
Declared platforms: desktop, mobile, web
Signature: map.camera.fitFeature(arg0: FeatureRef, arg1?: CameraFitOptions): Operation<void>

`map.camera.state`

Read the explicit CRS and resolution per logical pixel.

Permission: project.read
Declared platforms: desktop, mobile, web
Signature: map.camera.state(): Operation<CameraState>

`map.camera.setView`

Set center, resolution or EPSG:3857 standard zoom, plus 3D pitch/bearing. Positive pitch enters the 3D view.

Permission: map.write
Declared platforms: desktop, mobile, web
Signature: map.camera.setView(arg0: CameraViewOptions): Operation<void>

`map.camera.fitBounds`

Transform WGS84/Web Mercator bounds into the current view and fit them. A four-number array is interpreted as WGS84.

Permission: map.write
Declared platforms: desktop, mobile, web
Signature: map.camera.fitBounds(arg0: ViewBounds | [number,number,number,number], arg1?: CameraFitOptions): Operation<void>

`map.camera.fitAll`

Fit all visible layers.

Permission: map.write
Declared platforms: desktop, mobile, web
Signature: map.camera.fitAll(arg0?: CameraFitOptions): Operation<void>

map.lighting

`map.lighting.state`

Read lighting settings for globe and 3D building views.

Permission: project.read
Declared platforms: desktop, web
Signature: map.lighting.state(): Operation<SceneLightingState>

`map.lighting.set`

Set globe/3D-building light direction, intensity, backlighting, and solar time.

Permission: map.write
Declared platforms: desktop, web
Signature: map.lighting.set(arg0: SceneLightingOptions): Operation<SceneLightingState>

map.camera

`map.camera.focusWgs84`

Focus geographic coordinates; standard zoom is available in a Web Mercator view.

Permission: map.write
Declared platforms: desktop, mobile, web
Signature: map.camera.focusWgs84(arg0: [number,number], arg1?: {zoom?:number}): Operation<void>

map.features

`map.features.selection`

Read a revision-bound snapshot of the primary selected feature.

Permission: project.read
Declared platforms: desktop, mobile, web
Signature: map.features.selection(): Operation<FeatureRef | ClusterRef | null>

`map.features.selectionSet`

Read a multiple-selection snapshot for one dataset.

Permission: project.read
Declared platforms: desktop, mobile, web
Signature: map.features.selectionSet(): Operation<FeatureSetRef | null>

`map.features.clearSelection`

Clear current feature selection.

Permission: map.write
Declared platforms: desktop, mobile, web
Signature: map.features.clearSelection(): Operation<void>

`map.features.select`

Replace selection with the specified revision-bound feature.

Permission: map.write
Declared platforms: desktop, mobile, web
Signature: map.features.select(arg0: FeatureRef): Operation<void>

`map.features.selectSet`

Replace selection with the specified revision-bound feature set.

Permission: map.write
Declared platforms: desktop, mobile, web
Signature: map.features.selectSet(arg0: FeatureSetRef): Operation<void>

`map.features.get`

Read bounded, typed feature details.

Permission: project.read
Declared platforms: desktop, mobile, web
Signature: map.features.get(arg0: FeatureRef, arg1?: FeatureReadOptions): Operation<FeatureResult>

`map.features.query`

Query visible features using logical pixels in the map content area.

Permission: project.read
Declared platforms: desktop, mobile, web
Signature: map.features.query(arg0: MapFeatureQueryOptions): Operation<Page<MapHit>>

map.camera

`map.camera.centerOn`

Focus a place, coordinates, bounds, layer, or dataset. Place zoom follows administrative level: province 7, city 11, county 12, township 15.

Permission: map.write
Declared platforms: desktop, mobile, web
Signature: map.camera.centerOn(arg0: CenterOnTarget, arg1?: CenterOnOptions): Operation<void>