Globe projection and the common camera

Prefer the MapLibre-shaped call map.setProjection({ type: 'globe' }). SqsMap uses its own map engine. One Rust core implements spherical camera mathematics, geometry, tile coverage, depth, and labels. Similar call syntax does not imply complete MapLibre behavior compatibility.

Portable script

Use the same syntax in the web script console, desktop debug panel, and persistent sessions of standalone native libraries built with scripting enabled:

// @gis-api 0.5-session
// @permissions ["project.read", "map.write"]
import { map } from 'sqsmap';

map.jumpTo({ center: [116.4, 39.9], zoom: 1, bearing: 0 });
map.setProjection({ type: 'globe' });
const subscription = map.on('pitch', event => {
  console.log('Pitch changed', event.cameraState.camera.pitch);
});
map.jumpTo({ center: [116.4, 39.9], zoom: 2, bearing: 30, pitch: 30 });
await map.sqs.flush();
console.log(await map.getProjection());
console.log(await map.sqs.cameraState());
console.log(await map.project([116.4, 39.9]));
subscription.unsubscribe();

For the raw browser SDK, create a view using MapView from @sqsmap/core. Its confirmation method is await view.flush(), and its common camera query is await view.cameraState(). Legacy browser string arguments remain available. The string auto is a browser host preference, not a common projection specification.

Native libraries accept {"method":"setProjection","args":[{"type":"globe"}]} through the existing sqsm_map_camera_json entry. Camera reads, projection, and unprojection use the same entry. Release output with sqsm_map_bytes_free; the ABI version and existing symbols remain unchanged. Native libraries do not download HTTP resources: the host still pumps map resource requests and responses.

Units, limits, and switching

Positions use WGS84 [lng, lat]. Spherical latitude includes both poles. Zoom is 0–24, pitch is 0–65 degrees, and bearing follows the common normalized convention.
Projection and unprojection use logical pixels, or CSS pixels in browsers. Device pixel ratio is applied at the rendering boundary. Sky and points on the hidden side have no usable surface hit and return explicit errors.
Entering globe through the common specification preserves center and bearing, normalizing target zoom to the spherical 0–24 range. Explicitly returning to Mercator clamps latitude to approximately ±85.05113 degrees and resets pitch to zero.
Native sessions and browsers support geographic projection without a style basemap, preserving the poles. Style basemaps currently require Mercator or globe. Desktop GIS display coordinate systems must be changed through dedicated desktop APIs rather than implicitly converting existing data.

Events and confirmation

pitchstart, pitch, and pitchend use the same historical camera snapshot model as move, zoom, and rotate events. Start events retain the previous state; subsequent events retain the applied state. Event snapshots are immutable. Projection changes cancel the previous planar camera animation.

flush() confirms application. flush({ render: true }) also confirms an actual frame, but does not await all external resources. Native and desktop pixel capture report a not-ready error until a matching spherical frame exists. Browsers may initially show an empty canvas. Neither an old planar texture nor a sphere drawn for an older camera is presented as the current sphere.

Native and desktop receipts include the authoritative public cameraState. The retained legacy camera field is a planar compatibility representation without spherical pitch; it must not be used for spherical hit testing. Raw browser SDK receipts use camera.publicCamera; the browser script host exposes the common state as cameraState.

Failed commands remain in confirmation history. After inspecting a failure's submittedSequence, use that observed watermark as the since value of a subsequent barrier. A failed confirmation does not indicate successful application.

Scope of this stage

Connected operations include immediate center, zoom, bearing, and pitch reads/writes; jumpTo; surface project/unproject; north-and-pitch reset; and zoom/rotation/position commands explicitly using duration: 0. Spherical animation and anchored navigation are connected. Spherical bounds fitting and common spherical line/fill screen queries are connected. Globe roll is connected. Persistent padding keeps the geographic pose and shifts the screen principal point. Terrain, elevation queries, hillshade, lighting extensions, and other 3D layers have separate tasks.

Acceptance distinguishes mathematical and command checks, actual software GPU sphere pixels, browser main-thread and strict Worker execution, and device validation. Windows/macOS, mobile devices, and formal release packages require their own recorded results; Linux checks do not replace them.

Open the complete globe HTML example, including CSS and every button handler.

await map.sqs.getCapabilities() reports globeCamera: true, globeRendering: true, globeCameraAnimations: true, and globeCameraAnchors: true. Capability descriptions do not certify a particular dataset or device.

Unsupported spherical operations return CAPABILITY_UNAVAILABLE; invalid arguments return INVALID_ARGUMENT.

Shared circle rendering/queries and a separate background without user styles are connected; see spherical circle layers.

Shared spherical GeoJSON line/fill drawing and queries are connected: spherical surfaces.

Visible globe bounds connects getBounds to a conservative ground envelope including the date line and poles.