Skip to main content
SqsMapMaps and spatial data tools

Methods and complete examples

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.

Examples use synthetic demonstration data. They cannot substitute for a user's actual files, fields, or measurements. Discover real inputs first.

map.animations.line

Input: 2D line layer backed by a dataset with lineMetrics:true.

Output: PlaybackRef, with scene/playback references. Map export requires confirmation.

Units: durationMs is one-way milliseconds; progress:1 means the whole line, pixels means logical pixels. No meters-per-second or 3D.

Preconditions: Source, layer, and animation share owner:scene; scene.start() begins playback. Do not await finished() for a loop. Use one controller per layer; separate layers for combined large arrows and dashes. This synthetic example is not measured wind data.

// @gis-api 0.4-p2
// @permissions ["project.read","map.write","scene.run"]
import {gis,map} from 'gis';
const data=await gis.data.fromGeoJSON({type:'FeatureCollection',features:[{type:'Feature',properties:{},geometry:{type:'LineString',coordinates:[[102.7,25],[102.72,25.01]]}}]});
const scene=await map.scenes.create({id:'flow-demo',name:'流向示意'}),owner={owner:scene};
const source=await map.sources.add('flow',{type:'dataset',data,lineMetrics:true},owner);
const layer=await map.layers.add({id:'flow-line',type:'line',source,paint:{'line-color':'#2277cc','line-width':3}},owner);
const playback=await map.animations.line({layer,timing:{durationMs:2000,loop:true},effects:[{type:'flow'}]},owner);
await scene.start();
await map.camera.fitLayer(layer);
export default {scene,playback};

gis.data.layers

Input: Actual file path.

Output: Page.

Units: Each sublayer's CRS defines its bounds units.

Preconditions: Discover sublayers before selecting a layer in a multilayer file.

// @gis-api 0.4-p2
// @permissions ["project.read","analysis.execute"]
import {gis} from "gis";
export default await gis.data.layers('实际数据.gpkg',{limit:20});
  • args[0]: Use an actual file path.
  • args[1].cursor: Use only nextCursor from the preceding page.

gis.data.info

Input: DatasetRef, RasterRef, MapLayerRef, or TableRef.

Output: DatasetInfo, RasterInfo, or TableInfo.

Units: RasterInfo.bandInfo supplies scale, offset, and unit.

Preconditions: Check kind first; bands is a count, while bandInfo contains details.

// @gis-api 0.4-p2
// @permissions ["project.read","analysis.execute"]
import {gis} from "gis";
const source=await gis.data.open('实际影像.tif');
export default await gis.data.info(source);
  • args[0]: Use a reference that remains valid in the current task.

gis.data.fields

Input: Dataset or table reference.

Output: Page<FieldInfo | TableFieldInfo>.

Units: Table field units are supplied only when known.

Preconditions: Read all field pages and verify field names and code meanings.

// @gis-api 0.4-p2
// @permissions ["project.read","analysis.execute"]
import {gis} from "gis";
const source=await gis.data.fromGeoJSON({type:"FeatureCollection",features:[{type:"Feature",properties:{group:"A",value:2},geometry:{type:"Polygon",coordinates:[[[99,27],[99.001,27],[99.001,27.001],[99,27.001],[99,27]]]}}]});
export default await gis.data.fields(source,{limit:100});
  • args[1].cursor: Keep the same limit and pass nextCursor.

gis.query.rows

Input: Dataset or table reference.

Output: A Page whose rows contain a values object.

Units: Inherits result-field units.

Preconditions: Return bounded samples or result references rather than expanding all geometry.

// @gis-api 0.4-p2
// @permissions ["project.read","analysis.execute"]
import {gis} from "gis";
const source=await gis.data.fromGeoJSON({type:"FeatureCollection",features:[{type:"Feature",properties:{group:"A",value:2},geometry:{type:"Polygon",coordinates:[[[99,27],[99.001,27],[99.001,27.001],[99,27.001],[99,27]]]}}]});
export default (await gis.query.rows(source,{limit:20})).items.map(row=>row.values);
  • args[1].fields: Discover actual fields first.
  • args[1].cursor: Omit nextCursor after the last page; do not pass null.

gis.query.aggregate

Input: DatasetRef/FeatureSetRef plus grouping and measurements.

Output: TableRef.

Units: sumArea requires explicit m2/ha or other units; ordinary sum retains numeric-field semantics.

Preconditions: Use groupBy: for a total; separate grouping fields from measurement fields.

// @gis-api 0.4-p2
// @permissions ["project.read","analysis.execute"]
import {gis} from "gis";
const source=await gis.data.fromGeoJSON({type:"FeatureCollection",features:[{type:"Feature",properties:{group:"A",value:2},geometry:{type:"Polygon",coordinates:[[[99,27],[99.001,27],[99.001,27.001],[99,27.001],[99,27]]]}}]});
const fields=await gis.data.fields(source,{limit:100});
if(!fields.items.some(f=>f.name==="group"))throw Error("请确认分组字段");
const result=await gis.query.aggregate(source,{groupBy:["group"],measures:{n:{op:"count"},area:{op:"sumArea",unit:"ha"}},measurementCrs:"EPSG:32647"});
const page=await gis.query.rows(result,{limit:20});
export default {result,sample:page.items.map(row=>row.values),nextCursor:page.nextCursor};
  • args[1].groupBy: Discover fields first; use an empty array for a total.
  • args[1].measures.*.field: Numeric aggregation requires numeric fields.

gis.analysis.dissolve

Input: Polygon dataset/selection and grouping fields.

Output: DatasetRef retaining only grouping fields.

Units: outputCrs determines geometry coordinate units.

Preconditions: Requires valid 2D polygons; an empty groupBy dissolves all input.

// @gis-api 0.4-p2
// @permissions ["project.read","analysis.execute"]
import {gis} from "gis";
const source=await gis.data.fromGeoJSON({type:"FeatureCollection",features:[{type:"Feature",properties:{group:"A",value:2},geometry:{type:"Polygon",coordinates:[[[99,27],[99.001,27],[99.001,27.001],[99,27.001],[99,27]]]}}]});
const fields=await gis.data.fields(source,{limit:100});
if(!fields.items.some(f=>f.name==="group"))throw Error("请确认分组字段");
const result=await gis.analysis.dissolve(source,{groupBy:["group"],workingCrs:"EPSG:32647",outputCrs:"EPSG:4326"});
export default {result,info:await result.info()};
  • args[1].groupBy: Select actual grouping fields; use aggregate separately for other statistics.
  • args[1].workingCrs: Use a meter-based UTM projection covering the data.

gis.query.spatialJoin

Input: Left/right datasets or selections and field mappings.

Output: DatasetRef.

Units: outputCrs determines geometry CRS.

Preconditions: Specify left/inner and all/first explicitly; all may expand into one-to-many rows.

// @gis-api 0.4-p2
// @permissions ["project.read","analysis.execute"]
import {gis} from "gis";
const source=await gis.data.fromGeoJSON({type:"FeatureCollection",features:[{type:"Feature",properties:{group:"A",value:2},geometry:{type:"Polygon",coordinates:[[[99,27],[99.001,27],[99.001,27.001],[99,27.001],[99,27]]]}}]});
const result=await gis.query.spatialJoin(source,source,{relation:"intersects",join:"left",match:"all",fields:{left:{group:"leftGroup"},right:{group:"rightGroup"}},workingCrs:"EPSG:32647",outputCrs:"EPSG:4326"});
export default {result,info:await result.info()};
  • args[2].fields.left: Map actual source fields to unique output aliases.
  • args[2].fields.right: Left and right output aliases must not conflict.

gis.query.nearest

Input: Left/right datasets or selections.

Output: TableRef with distances and source-row indices.

Units: distanceM is meters; maxDistance includes an explicit unit.

Preconditions: Bound k and distance, and select a ties policy. Row indices are not business identifiers.

// @gis-api 0.4-p2
// @permissions ["project.read","analysis.execute"]
import {gis} from "gis";
const source=await gis.data.fromGeoJSON({type:"FeatureCollection",features:[{type:"Feature",properties:{group:"A",value:2},geometry:{type:"Polygon",coordinates:[[[99,27],[99.001,27],[99.001,27.001],[99,27.001],[99,27]]]}}]});
const result=await gis.query.nearest(source,source,{k:1,maxDistance:{value:100,unit:"m"},measurementCrs:"EPSG:32647",ties:"all"});
const page=await gis.query.rows(result,{limit:20});
export default {result,sample:page.items.map(row=>row.values),nextCursor:page.nextCursor};
  • args[2].maxDistance: Supply both value and unit.
  • args[2].measurementCrs: Use a UTM projection covering both inputs.

gis.data.reproject

Input: DatasetRef/FeatureSetRef and outputCrs.

Output: Independent DatasetRef.

Units: Coordinate units follow the target CRS.

Preconditions: Transforms coordinates rather than changing only their label.

// @gis-api 0.4-p2
// @permissions ["project.read","analysis.execute"]
import {gis} from "gis";
const source=await gis.data.fromGeoJSON({type:"FeatureCollection",features:[{type:"Feature",properties:{group:"A",value:2},geometry:{type:"Polygon",coordinates:[[[99,27],[99.001,27],[99.001,27.001],[99,27.001],[99,27]]]}}]});
export default await gis.data.reproject(source,{outputCrs:"EPSG:32647"});
  • args[1].outputCrs: Use a supported 2D EPSG CRS.

gis.raster.warp

Input: RasterRef, target CRS/grid, resampling, and dataKind.

Output: RasterRef.

Units: Bounds use outputCrs units.

Preconditions: The example grid applies only to the example; verify real bounds and resolution before running.

// @gis-api 0.4-p2
// @permissions ["project.read","analysis.execute"]
import {gis} from "gis";
const source=await gis.data.open('实际影像.tif');
export default await gis.raster.warp(source,{outputCrs:'EPSG:32647',grid:{bounds:[500000,0,500040,40],width:4,height:4},resampling:'nearest',dataKind:'categorical'});
  • args[1].grid.bounds: Bounds must use the target CRS.
  • args[1].resampling: Categorical data permits only nearest resampling.

gis.raster.readPixels

Input: RasterRef, band, and pixel window.

Output: PixelBlock with bounded numeric arrays and null for invalid pixels.

Units: physical applies scale/offset; raw does not infer physical units.

Preconditions: Check dimensions and bandInfo first; analysis reads are not display resampling.

// @gis-api 0.4-p2
// @permissions ["project.read","analysis.execute"]
import {gis} from "gis";
const source=await gis.data.open('实际影像.tif');
export default await gis.raster.readPixels(source,{band:1,window:{xOffset:0,yOffset:0,width:1,height:1},values:'physical'});
  • args[1].band: Band indices start at 1.
  • args[1].window: Offsets, width, and height are source-grid pixels.

gis.raster.zonalStats

Input: RasterRef and polygon DatasetRef/FeatureSetRef.

Output: TableRef with statistics, validCount, and noDataCount.

Units: Choose raw/physical explicitly; rasterValues records table units.

Preconditions: Zone IDs must be unique and non-null. Pixel-center selection includes boundaries, treats overlaps independently, and does not resample.

// @gis-api 0.4-p2
// @permissions ["project.read","analysis.execute"]
import {gis} from "gis";
const source=await gis.data.open('实际影像.tif');
const zones=await gis.data.fromGeoJSON({type:'Feature',properties:{zone:'demo'},geometry:{type:'Polygon',coordinates:[[[98.9999,-0.0001],[99.0005,-0.0001],[99.0005,0.0005],[98.9999,0.0005],[98.9999,-0.0001]]]}});
const result=await gis.raster.zonalStats(source,zones,{zoneIdField:'zone',band:1,statistics:['mean','count'],values:'physical',nodata:'exclude',pixelInclusion:'center'});
const page=await gis.query.rows(result,{limit:20});
export default {result,sample:page.items.map(row=>row.values),nextCursor:page.nextCursor};
  • args[2].zoneIdField: Verify the actual field and uniqueness.
  • args[2].statistics: Use a nonempty list without duplicates; all-invalid numeric statistics are null.

gis.query.sql

Input: Source aliases bound to DatasetRef/FeatureSetRef/TableRef and positional ? parameters.

Output: Explicit TableRef or DatasetRef.

Units: SQL does not reproject data or infer measurement units.

Preconditions: Restricted local SQLite only. Select table attributes explicitly without geom; spatial result CRS comes from source info().crs, not the measurement projection.

// @gis-api 0.4-p2
// @permissions ["project.read","analysis.execute"]
import {gis} from "gis";
const source=await gis.data.fromGeoJSON({type:"FeatureCollection",features:[{type:"Feature",properties:{group:"A",value:2},geometry:{type:"Polygon",coordinates:[[[99,27],[99.001,27],[99.001,27.001],[99,27.001],[99,27]]]}}]});
const result=await gis.query.sql({text:'SELECT value FROM p WHERE "group"=?',sources:{p:source},bindings:["A"],dialect:"sqlite",result:{type:"table"}});
const page=await gis.query.rows(result,{limit:20});
export default {result,sample:page.items.map(row=>row.values),nextCursor:page.nextCursor};
  • args[0].sources.*: Register the same reference under two aliases without copying it first.
  • args[0].bindings: Match each positional ? to a bindings entry; do not concatenate values.
  • args[0].result: For features, select source geom directly and validate its actual CRS.

Method sources and unsupported scope

These notes explain methodology; they do not add executable APIs. Source filenames identify knowledge inputs and do not require installing that directory.

空间SQL-融合Dissolve与单多部件.md

Dissolve removes overlap within groups. The sum of input areas and the dissolved coverage area measure different quantities.

Preconditions: Verify grouping fields and the intended area measure first. Dissolve retains only grouping fields.

Current APIs: analysis.dissolve, query.aggregate

Unsupported scope: Collect, multipart splitting, and spatial SQL Union are not enabled by this method batch.

Source SHA-256: f218f70e8f7f5a37691685164d947d96d6192291fdd5cde76fe1fad0fb496331.

空间SQL-面积ST_Area与坐标系单位.md

Area and distance require an explicit measurement projection and unit. Square degrees are not square meters.

Preconditions: Current measurements use a suitable UTM meter projection covering the data; arbitrary projections are not supported.

Current APIs: query.aggregate, query.nearest, data.reproject

Unsupported scope: PostGIS geography and source-specific two-argument area functions are not generic published capabilities.

Source SHA-256: 59d2b7f3089d56f8c4fb447f2d48cea0460cd051c984dde511ffee9720f4dc3e.

场景-NoData当0.md

Zero can be a valid value. Use band masks and NoData metadata; do not replace missing data with zero.

Preconditions: Read bandInfo and choose raw/physical first. All-invalid zone numeric statistics are null.

Current APIs: raster.readPixels, raster.zonalStats, data.info

Unsupported scope: This batch does not provide NoData metadata changes or raster algebra.

Source SHA-256: e33f5c5379c9ffad179c1441bd9557bfc99021eb5dac07054b62327859572987.

场景-分类图重投影.md

Resampling categorical values must not create new categories; this batch uses nearest.

Preconditions: Verify dataKind, target CRS, and the explicit target grid first.

Current APIs: raster.warp

Unsupported scope: Source-document mode/cubic, polygonize, and compression options cannot be copied into these interfaces.

Source SHA-256: 1f2dfaad3ba80ab6b04f51b21014f336a5dfc4ea9d059d14da99deb180e7c55f.

GDAL-gdalwarp窗口与分辨率.md

Output bounds use the target CRS. Width and height determine target resolution; read windows use pixel indices.

Preconditions: Verify the grid against the business requirement; geographic degrees cannot be used as projected meter bounds.

Current APIs: raster.warp, raster.readPixels

Unsupported scope: Command-line options such as -tap are not script options.

Source SHA-256: 21146b9dae2d09a566c8f85c81148bf20c807f7a47a47c8b64a474032b8f2bd0.