@focus-daima/gis-workbench 0.0.0-stage → 0.9.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,3 +1,350 @@
1
- # Temporary Holding Version
1
+ # GIS workbench
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ A persistent DSH Web plugin (bundle `@focus-daima/gis-workbench`) that adds:
4
+
5
+ - a MapLibre GL JS workbench panel with an **empty initial layer list**;
6
+ - a collapsible right-side conversation panel;
7
+ - a Host tool `gis_add_layer` that the conversation calls to add raster layers;
8
+ - a Client tool view that applies each successful add-layer result to the map store.
9
+
10
+ ## Installation in another DSH profile
11
+
12
+ The package is published to the internal Nexus npm hosted repository
13
+ `https://your-nexus-host/repository/frontend/`.
14
+
15
+ Configure the scope once for the target user:
16
+
17
+ ```bash
18
+ npm config set @focus-daima:registry https://your-nexus-host/repository/frontend/
19
+ dsh plugin --profile web add @focus-daima/gis-workbench@0.9.9
20
+ dsh web
21
+ ```
22
+
23
+ A local tarball also works:
24
+
25
+ ```bash
26
+ npm pack
27
+ dsh plugin --profile web add ./focus-daima-gis-workbench-0.9.9.tgz
28
+ ```
29
+
30
+ Required runtime: Node.js with `node:sqlite`, GDAL CLI (`ogr2ogr`,
31
+ `gdal_translate`, `gdalinfo`, `gdal2tiles.py`), and Python 3 with GDAL
32
+ bindings. PostGIS registration additionally needs `psycopg`.
33
+
34
+ The default Tianditu tile service is deployment-specific. Replace
35
+ `DEFAULT_TILE_URL` in `shared.js` or configure the tile URL through the API if
36
+ the target Harness cannot reach the current internal service.
37
+
38
+ ## Source and build
39
+
40
+ `client.js` is generated by esbuild from `src/client.entry.js`. It bundles
41
+ `maplibre-gl@5.24.1` and inlines `maplibre-gl/dist/maplibre-gl.css`. MapLibre is the
42
+ open-source fork of Mapbox GL JS and needs no access token.
43
+
44
+ Mapbox GL JS 3.x revokes the renderer when no valid access token is configured:
45
+ the map keeps requesting raster tiles (they answer 200) but paints a blank
46
+ canvas. That is why this plugin uses MapLibre instead. Switching back to
47
+ Mapbox requires setting a real token before creating the map.
48
+
49
+ The dependency and bundler were installed from the Nexus npm registry:
50
+
51
+ ```bash
52
+ npm install --registry=https://your-nexus-host/repository/nexus-npm/ \
53
+ maplibre-gl@5.24.1 esbuild@0.28.2
54
+ ```
55
+
56
+ Build from the repository root after making the installed `node_modules`
57
+ available to esbuild:
58
+
59
+ ```bash
60
+ ./node_modules/.bin/esbuild src/client.entry.js \
61
+ --bundle --format=iife --platform=browser --target=es2020 \
62
+ --loader:.css=text --define:process.env.NODE_ENV='"production"' \
63
+ --minify --legal-comments=inline --outfile=client.js
64
+ ```
65
+
66
+ ## Default tile layer
67
+
68
+ `shared.js` owns the default Tianditu image template:
69
+
70
+ ```text
71
+ //your-tile-host/api/gis-map-service/world-map-tiles/images/tiandi-image-3857/{z}/{x}/{y}
72
+ ```
73
+
74
+ Calling `gis_add_layer` with no arguments adds this layer. The Client resolves
75
+ the protocol-relative template against the page protocol before handing it to
76
+ the map engine.
77
+
78
+ ## Shared map chat
79
+
80
+ The right-hand map chat uses the **current Session** rather than a separate
81
+ Session. DSH's right sidebar is session-bound: showing a separate Session's chat
82
+ requires navigating the main workspace to that Session, which can expose a
83
+ duplicate conversation if the workbench overlay is lost. Using the current
84
+ Session keeps the main workspace fixed while the overlay covers it.
85
+
86
+ - Opening the workbench opens the map-chat tab in the current Session's right
87
+ sidebar and leaves the main Session unchanged.
88
+ - The chat and the center conversation share model context, history, and draft,
89
+ but the overlay hides the center while the workbench is open.
90
+ - **Original layout** closes the overlay, closes the map-chat tab, and restores
91
+ the previous right-sidebar tab.
92
+ - Map layers live in one module-level store, so tool calls from the chat update
93
+ the same workbench map.
94
+
95
+ ## Layout entry points
96
+
97
+ - **GIS** button in the session header enters the workbench.
98
+ - **Original layout** in the workbench top bar returns to the previous Session.
99
+ - The right panel can be collapsed from its own chevron or the top-bar
100
+ **Conversation** control.
101
+ ## Projects, datasets, and layers
102
+
103
+ State is persisted in SQLite at `<Host workspace>/.gis-workbench/gis.sqlite`
104
+ (the Host workspace is `/app` in the current deployment; uploaded files go to
105
+ `.gis-workbench/uploads`). The Host plugin exposes:
106
+
107
+ ```text
108
+ GET /api/gis-workbench
109
+ POST /api/gis-workbench/projects
110
+ GET /api/gis-workbench/projects/:id/datasets
111
+ POST /api/gis-workbench/projects/:id/datasets
112
+ POST /api/gis-workbench/projects/:id/datasets/upload
113
+ POST /api/gis-workbench/projects/:id/datasets/tile
114
+ GET /api/gis-workbench/projects/:id/layers
115
+ POST /api/gis-workbench/projects/:id/layers
116
+ PATCH /api/gis-workbench/layers/:id
117
+ DELETE /api/gis-workbench/layers/:id
118
+ DELETE /api/gis-workbench/datasets/:id
119
+ GET /api/gis-workbench/datasets/:id/content
120
+ GET /api/gis-workbench/browse?path=...
121
+ ```
122
+
123
+ Tables follow the requested model: `projects`, `datasets`, `layers`. SQLite has
124
+ no built-in geometry type, so `bbox` is a JSON array
125
+ `[west, south, east, north]` (WGS84). `meta`, `profile`, and `style` are JSON
126
+ text columns. Foreign keys cascade dataset deletion to its layers.
127
+
128
+ Datasets can be:
129
+
130
+ - browsed from an allowed server directory (default roots: the Host workspace,
131
+ `/home/agent`, `/data`, `/mnt/data`, `/srv/data`; override with the
132
+ colon-separated `GIS_WORKBENCH_ROOTS` environment variable);
133
+ - uploaded as GeoJSON, JSON, CSV, GeoTIFF, PNG/JPEG/WebP, `.shp`, or `.zip`;
134
+ - registered from an XYZ tile URL.
135
+
136
+ The map renders tile datasets, GeoJSON datasets through the same-origin content
137
+ route, and image datasets with a known bbox. GeoTIFF and Shapefile datasets are
138
+ registered and managed but need tiling/conversion before they can be drawn.
139
+
140
+
141
+ ## Saving project layer state
142
+
143
+ Layer visibility, ordering, and removal are edited locally so the map updates
144
+ immediately. The top-bar **Save project** button commits the complete project
145
+ layer list atomically through `PUT /api/gis-workbench/projects/:id/state`;
146
+ the Host replaces that project's layers in one SQLite transaction. Leaving the
147
+ workbench, switching projects, opening the dataset manager, or creating a
148
+ project saves unsaved layer edits first. A dirty indicator and a browser
149
+ unload warning remain until the save succeeds.
150
+
151
+ ## Chunked, resumable uploads
152
+
153
+ The upload tab no longer sends the whole file in one multipart request, so the
154
+ old 200 MB request-body limit does not apply. Files are capped at **100 GB** and
155
+ uploaded in 8 MB chunks:
156
+
157
+ ```text
158
+ POST /api/gis-workbench/projects/:id/uploads/init
159
+ GET /api/gis-workbench/uploads/:id
160
+ PUT /api/gis-workbench/uploads/:id/chunks/:index
161
+ POST /api/gis-workbench/uploads/:id/complete
162
+ DELETE /api/gis-workbench/uploads/:id
163
+ ```
164
+
165
+ `uploads` rows in SQLite track the file fingerprint, chunk size, received chunk
166
+ indexes, and temporary path. Re-selecting the same file resumes from the server's
167
+ recorded chunks; the client also remembers the upload id in `localStorage`. The
168
+ upload tab shows byte/percentage progress and a pause button. The Host accepts
169
+ each chunk up to 64 MB and writes it at its final offset, so neither memory nor
170
+ the HTTP body limit scales with the whole file.
171
+
172
+ ## GeoTIFF → COG and display
173
+
174
+ A `.tif`/`.tiff` dataset is converted during registration (and can be converted
175
+ again for an existing dataset from the dataset card):
176
+
177
+ 1. `gdal_translate -of COG` writes `derived/<datasetId>/data.cog.tif` with
178
+ DEFLATE compression and COG overviews;
179
+ 2. `gdalinfo -json` supplies the WGS84 extent and CRS;
180
+ 3. `gdal2tiles.py --xyz -p mercator -z 0-<cap>` writes an XYZ PNG pyramid under
181
+ `derived/<datasetId>/tiles`;
182
+ 4. the dataset profile becomes `format: "cog"` with `minzoom`, `maxzoom`,
183
+ `tilesUrl`, and the map adds a raster source using
184
+ `/api/gis-workbench/datasets/:id/tiles/{z}/{x}/{y}.png`;
185
+ 5. the map fits the layer's WGS84 bounds.
186
+
187
+ The zoom cap is derived from the raster's geographic coverage (at most zoom 22,
188
+ and fewer levels for large extents, keeping the pyramid under roughly 6,000
189
+ tiles) to bound tile generation. The original TIF is preserved in the upload
190
+ directory; the dataset URI points at the derived COG.
191
+
192
+ ## Vector import: SHP, GeoJSON, GeoPackage, and ZIP
193
+
194
+ Vector uploads are normalized into a project-scoped GeoPackage
195
+ (`data/projects/<projectId>.gpkg`) with one layer per imported dataset. The
196
+ original upload stays in the upload directory as the immutable source; the
197
+ catalog SQLite stores the dataset/layer metadata and the GeoPackage table name.
198
+
199
+ - `.geojson` / GeoJSON `.json`: imported with `ogr2ogr` to GPKG, converted to
200
+ EPSG:4326, with a spatial index and a derived GeoJSON display preview.
201
+ - `.shp`: imported when its sidecars (`.shx`, `.dbf`, `.prj`, `.cpg`) are
202
+ present. ZIP is the recommended upload for Shapefiles.
203
+ - `.gpkg`: every vector layer in the GeoPackage is imported as a separate
204
+ dataset.
205
+ - `.zip`: safely extracted with a Python helper, then every contained SHP,
206
+ GeoJSON, and GPKG layer is detected and imported. All supported sources in one
207
+ archive produce multiple datasets/layers and are returned as arrays by the API.
208
+ - SHP/GeoJSON/GPKG are transformed to EPSG:4326 using `ogr2ogr -makevalid`; the
209
+ GeoPackage remains the canonical editable/queryable store.
210
+ - MapLibre currently draws the derived GeoJSON preview. Large layers should be
211
+ upgraded to MVT tiles later; the GPKG is already indexed for that step.
212
+
213
+ ## Building labels
214
+
215
+ A vector layer whose name contains `building` and whose fields include `CODE`
216
+ gets a MapLibre symbol layer on top of its fill/line rendering. The `CODE`
217
+ value is translated for display:
218
+
219
+ | CODE | Label |
220
+ | --- | --- |
221
+ | Building | 建筑 |
222
+ | Deck | 露台 |
223
+ | Patio | 庭院 |
224
+ | Cement Pad | 混凝土地坪 |
225
+ | Greenhouse | 温室 |
226
+ | Foundation | 地基 |
227
+ | Ruins | 废墟 |
228
+
229
+ Unknown codes keep their original text, and null/empty codes draw no label.
230
+ Labels start at zoom 15; from zoom 12.5 only footprints larger than 10,000
231
+ (`ShapeSTAre`) are labelled so the overview stays readable. CJK glyphs are
232
+ rasterized locally by MapLibre, so no glyph PBF endpoint is required.
233
+
234
+ ## Semantic layer styling tools
235
+
236
+ The Host exposes MCP-style map styling tools (visible to the conversation
237
+ agent), backed by the shared `style-schema.js` contract:
238
+
239
+ ```text
240
+ gis_list_layers find layers by name/project/field
241
+ gis_describe_layer inspect format, fields, bbox, feature count, style
242
+ gis_sample_field distinct field values for translation/valueMap
243
+ gis_map_capabilities style schema, fonts, glyph URL, examples
244
+ gis_update_layer_style persist a semantic style patch for one layer
245
+ ```
246
+
247
+ `gis_update_layer_style` accepts `fillColor`, `fillOpacity`, `lineColor`,
248
+ `lineWidth`, `lineOpacity`, `circleColor`, `circleRadius`, `circleOpacity`,
249
+ `circleOpacity`, `lineVisible`, `circleVisible`, `categorical`, `opacity`, and `label`. Label supports `field`, `valueMap`, `fallback`, `size`,
250
+ `color`, `haloColor`, `haloWidth`, `minzoom`, `maxzoom`, `allowOverlap`, `font`,
251
+ and `anchor`. Example:
252
+
253
+ ```json
254
+ {
255
+ "fillColor": "#d8cbb4",
256
+ "label": {
257
+ "field": "CODE",
258
+ "valueMap": {
259
+ "Building": "建筑",
260
+ "Deck": "露台",
261
+ "Patio": "庭院"
262
+ },
263
+ "size": 12,
264
+ "minzoom": 14
265
+ }
266
+ }
267
+ ```
268
+
269
+ Styles are persisted in `layers.style` and a client tool view applies the patch
270
+ to the live layer store. MapLibre renders labels as a symbol layer. Latin glyph
271
+ ranges are served from `assets/glyphs` at
272
+ `/api/gis-workbench/glyphs/{fontstack}/{range}.pbf`; missing CJK ranges fall
273
+ back to MapLibre's local ideograph renderer (`localIdeographFontFamily`).
274
+
275
+ ## Map styling skill
276
+
277
+ A local skill at `/home/agent/.dsh/skills/gis-map-styling/SKILL.md` encodes the
278
+ general workflow: find layer → inspect fields → sample values → translate via
279
+ `valueMap` → persist the semantic style. The model-facing skill and the Host MCP
280
+ tools share the same style contract, so new layer-label or recolor requests do
281
+ not need a dedicated tool.
282
+
283
+ ## PostgreSQL / PostGIS registration
284
+
285
+ The dataset manager has a **Database** tab. It registers a PostgreSQL
286
+ connection per project and lists spatial tables from PostGIS
287
+ `geometry_columns`. Selecting a table imports it into the project GeoPackage
288
+ with the same vector pipeline used for uploads, then adds it as a layer.
289
+
290
+ Endpoints:
291
+
292
+ ```text
293
+ GET /api/gis-workbench/projects/:id/databases
294
+ POST /api/gis-workbench/projects/:id/databases
295
+ DELETE /api/gis-workbench/databases/:id
296
+ GET /api/gis-workbench/databases/:id/tables
297
+ POST /api/gis-workbench/databases/:id/tables/import
298
+ ```
299
+
300
+ The registration stores host, port, database, username, password, and sslmode in
301
+ the catalog SQLite. Passwords are not returned by the API. Import uses
302
+ `ogr2ogr` with the GDAL PostgreSQL driver; the password is passed through
303
+ `PGPASSWORD`, not the command line. Tables are copied to the project GPKG, so a
304
+ later refresh/re-import is explicit rather than live-linked.
305
+
306
+ ## Add a layer to the conversation
307
+
308
+ Right-click any row in the layer panel and choose **添加到对话**. The workbench
309
+ collects the layer name, layerId (or session layer key), project, dataset
310
+ type/format, feature count, attribute fields, bbox, and a short current-style
311
+ summary, then appends that structured context to the active map-chat draft. The
312
+ single action also opens/focuses the map-chat tab. A small composer-bridge slot
313
+ captures the active Session's `inputActions` so the overlay can write the draft
314
+ without replacing the main workspace.
315
+
316
+ ## Layer ordering
317
+
318
+ Layer-panel rows are draggable. Dropping above/below another row reorders the
319
+ shared layer store immediately, normalizes `z`, and moves the corresponding
320
+ MapLibre layer groups to match. Reordering a project layer saves the project
321
+ layer order automatically; session-only ordering stays local.
322
+
323
+ ## New polygon vector layers
324
+
325
+ The layer panel's **+** action creates a project-scoped GeoPackage polygon
326
+ layer (`sourceFormat: "drawn"`, fields `name` and `created_at`) and immediately
327
+ enters polygon drawing mode. Left-click adds vertices; right-click, **Finish**,
328
+ or the panel button closes the ring and saves the polygon through
329
+ `POST /api/gis-workbench/datasets/:id/features`. The layer preview and bbox are
330
+ rebuilt after each save, and the GeoJSON source is refreshed through a
331
+ feature-count/size version query. Escape cancels the drawing.
332
+
333
+ Drawn layers expose a pencil action in the layer panel to re-enter polygon
334
+ drawing and append more polygons to the same GeoPackage layer. During drawing
335
+ the map shows a rubber-band line from the last vertex and a live polygon preview
336
+ under the cursor; committed vertices and the preview use separate GeoJSON
337
+ sources so the preview can change on every mouse move.
338
+
339
+ Drawn polygons support right-click deletion. The map queries rendered features in
340
+ drawn layers, opens a small context menu on the polygon, and deletes the matching
341
+ feature by `name` + `created_at` through
342
+ `POST /api/gis-workbench/datasets/:id/features/delete`. The preview, feature
343
+ count, and actual bbox are rebuilt from the remaining features.
344
+
345
+ Drawn polygons support an edit mode from the pencil action: click a polygon to
346
+ show its vertices, drag a vertex marker to reshape it, or drag inside the
347
+ polygon to move the whole feature. Each drag finish saves geometry through
348
+ `POST /api/gis-workbench/datasets/:id/features/update`. Source refresh uses a
349
+ profile revision (`updatedAt`) instead of clearing project layers, preventing the
350
+ map from flashing white after edits or feature deletion.
Binary file
Binary file
Binary file
Binary file
Binary file