Skip to main content
SqsMapMaps and spatial data tools

Raster sources in standard styles

Version-8 raster sources and layers now use shared planar and spherical painters. Browser main thread, strict map Worker and native libraries share compilation, decoding and scheduling; desktop reuses the same session. Applications supply UI, buttons and provider links.

Save this JSON at a reachable style URL, replace endpoints with the actual provider's values, and load it with map.setStyle(url, {diff:false}). ArcGIS templates use level/row/column, or z/y/x.

{
  "version": 8,
  "sources": {
    "satellite": {
      "type": "raster",
      "tiles": ["https://services.arcgisonline.com/ArcGIS/rest/services/World_Imagery/MapServer/tile/{z}/{y}/{x}"],
      "tileSize": 256,
      "minzoom": 0,
      "maxzoom": 18,
      "attribution": "Source: Esri, Vantor, Earthstar Geographics, and the GIS User Community"
    }
  },
  "layers": [{
    "id": "satellite", "type": "raster", "source": "satellite",
    "paint": {
      "raster-opacity": 1,
      "raster-resampling": "linear",
      "raster-brightness-min": 0,
      "raster-brightness-max": 1,
      "raster-saturation": 0,
      "raster-contrast": 0,
      "raster-hue-rotate": 0,
      "raster-fade-duration": 0
    }
  }]
}

Shared scripts and standalone SDK

// @gis-api 0.5-session
// @permissions ["project.read", "map.write"]
import { map } from 'sqsmap';
map.setStyle('https://www.sqsmap.com/styles/arcgis-satellite.json', { diff: false });
await map.sqs.flush();
console.log(await map.sqs.getCapabilities());
console.log(await map.sqs.getAttributions());

flush confirms command application, not download completion. The standalone SDK uses view.flush(), view.sqs.getCapabilities(), view.getAttributions() and view.onAttributionsChange(). Native libraries retain sqsm_map_set_style_json: {"style":"absolute HTTP(S) style URL","options":{"diff":false}}. Hosts pump requests, download within resource.maxBytes and return bytes. The core has no HTTP client. See native API and resource policy.

Complete HTML/CSS/JavaScript includes every load, north/south, zoom and destroy handler, errors, command watermarks, attribution subscriptions and page-exit cleanup. ArcGIS requests try the original service, then the site relay on connectivity failure; only matching imagery Tile requests use that fallback. Esri and World Imagery source links remain visible. Applications must check and retain their provider's requirements; metadata can change, and failed metadata retrieval must not erase known credits. The site also serves the standard style JSON.

Source and layer rules

  • Mutually exclusive url / tiles, TileJSON, relative templates, 1–8 mirrors, XYZ/TMS, bounds and explicit metadata overrides follow the vector tile source rules. Invalid metadata does not partially commit templates, bounds or attribution.
  • tileSize accepts 256 or 512, default 512. Public zoom uses a 512-pixel reference; a 256 source requests one higher physical level at the same map zoom. Source levels are integers 0–24, default 0/22. Below-min views do not request tiles; above-max views overzoom cached tiles.
  • PNG, JPEG and WebP decode to straight-alpha RGBA8. Encoded data is limited to 4 MiB, sides to 512 pixels and decoded pixels to 1 MiB per image. Vector/imagery tiles share a 64 MiB CPU cache. Planar imagery has a separate 64 MiB texture budget and at most 512 quads. Limits report explicit errors; non-visible data is evicted, and replacement/destruction release textures and generations.
  • Opacity and brightness values use 0–1; saturation and contrast use -1–1. Hue is finite, bounded here to ±1 billion degrees and normalized before painting. Numbers and zoom stops/step/interpolate expressions work; feature/state expressions, invalid values and unknown properties are rejected.
  • Resampling accepts linear/nearest. Opacity and color controls affect actual textures. Imagery, fills, lines, icons and text share style order. Hidden or out-of-layer-zoom imagery does not schedule tiles. Source bounds select tiles without clipping their internal pixels.
  • Raster layers cannot reference vector/GeoJSON sources, source-layer or feature filters. Vector layers cannot reference raster sources. Credits retain source and referencing-layer provenance.

Current boundaries

styleRasterPlanarSources, styleRasterGlobeSources and styleRasterFade are true. Complete styleRasterSources and cross-host planar pitch (styleRasterPitchedSources) remain false. Spherical pitch uses the shared globe camera. The Rust perspective painter also supports imagery; the shared planar pitched camera and terrain draping remain active work. This is not a claim of full MapLibre compatibility.

Shared SourceStore raster/vector/raster-dem lifecycle, common-script setStyle(object), incremental style edits, mobile script hosts, external devices and formal releases remain pending. Standard raster styles are separate from existing standalone XYZ/GIS imagery layers. This page and the matching SDK are development snapshots; local software-GPU acceptance does not imply hardware, mobile or remote deployment acceptance.

Globe imagery and complete handlers

For the same loaded style, call map.setProjection({type:'globe'}), then map.jumpTo({center:[0,45],zoom:1,pitch:30}). Return with map.setProjection({type:'mercator'}). Opacity, color, nearest sampling, TMS, 256-pixel sources and parent-tile crops keep the same parameters. Real curved meshes preserve Mercator texture interpolation and depth occlusion.

Complete globe imagery HTML contains all load, hemisphere, zoom, globe, planar, spherical-pitch and destroy handlers, attribution subscriptions and cleanup. The shared script runs unchanged in browser main thread, strict Worker, native one-shot and persistent script entries. Event subscriptions need a persistent session; native one-shot entries do not provide long-lived subscriptions. flush confirms command application while streaming tiles and curved geometry can arrive later; wait for actual loading/frame readiness.

Perspective imagery retains separate 64 MiB texture and vertex budgets and at most 512 patches. Layers and cropped parent patches reuse immutable image textures; exceeding limits reports errors. Terrain draping and complete shared SourceStore lifecycle remain active work. Renderer support does not imply a pitched-camera binding exists in every host.

Tile fading

raster-fade-duration is measured in milliseconds, defaults to 300, and accepts nonnegative finite constants and zoom stops/step/interpolate expressions. Use 0 for immediate display. The example above disables fade to make color adjustment easier to observe. A new image fades in; an available ancestor is cropped to the same region and mixed with the new image before applying layer opacity once. Transparent pixels do not accumulate opacity. Retained parent bytes count against the shared CPU tile budget. Completed transitions release the retained image; GPU textures follow actual usage. A visible transition schedules repaint every 16ms, paints the complete final frame, then stops requesting frames.

The complete fade HTML includes every zoom, globe/flat, attribution, error and destroy handler, with main-thread or strict Worker rendering. The default imagery retains Esri attribution and source links, and uses a configurable same-site proxy after a direct request fails. Shared scripts use the same Style JSON property. styleRasterFade covers tile arrival fading; video, property transitions and complete SourceStore lifecycle remain separate tasks. Semantics follow the public MapLibre raster property; SqsMap provides its own rendering and resource implementation.

Shared tile URL templates extend quadkey, bbox, prefix, ratio and actual density changes. Earlier batch evidence remains historical; full source parameters remain separately pending.

Effective tile metadata documents current overrides, actual sizing/DEM decoding and accepted data during refresh waits/failures. Earlier evidence is not relabeled.