ixmaps-gl 0.2.33 → 0.2.34

package/README.md

@@ -114,8 +114,8 @@ page. It currently implements:
   `window.__setFacetFilter`) for building filterable sidebars
 - Globe (orthographic) projection alongside flat Mercator
 
-Not yet implemented: the `QUAD`/`WAFFLE` base types. Custom SYMBOL shapes are supported
-as image-URL symbols (`symbols: [...]`), not as built-in shape variants.
+Not yet implemented: the `QUAD`/`WAFFLE` base types. SYMBOL shapes: the built-in ones and image-URL
+symbols are described under [Symbols](#symbols).
 The top-of-file comment in [`ixmaps-gl.js`](./ixmaps-gl.js) is the single source of truth
 for scope; this list only summarises it.
 
@@ -329,12 +329,152 @@ so zoom-dependent page state (e.g. a basemap opacity ramp) changes in step with
 hooks) aren't supported. `test/project-report.mjs` shows which themes
 of your own project files gl can render.
 
+### Symbols
+
+`CHART|SYMBOL` draws one symbol per item (per category with `CATEGORICAL`, per part with `SEQUENCE`).
+`style.symbols` names them, by color class: class `i` (the `i`-th entry of `values`, else the range
+class) takes `symbols[i]`, and the last entry repeats when the array is shorter than the classes.
+
+- **Built-in shapes:** `circle` (default), `square`, `diamond` (= `carot`), `triangle`, `roundrect`,
+  `hexagon`, `cross`, `label`, `empty`. An unknown name draws a circle.
+- **Image symbols:** a URL ending in `.svg`, `.png`, `.jpg` or `.jpeg` (a query or `#` may follow), or a
+  `data:image/svg+xml|png|jpeg` URI. The image is drawn as is, not tinted by the class color. An SVG is
+  fetched and rasterized once per URL (a `viewBox` is enough, it needs no width/height); a PNG/JPEG is
+  loaded by deck.gl. A page opened from `file://` cannot fetch symbol files: serve it over http(s) or use
+  `data:` URIs.
+- **By record field:** `symbolfield: "type"` with `symbolvalues: ["a", "b"]` maps the value of that field
+  to `symbols[i]` by position, independent of the color class (for individual items, not aggregated cells).
+
+```js
+.type("CHART|SYMBOL|CATEGORICAL")
+.style({ values: ["school", "shop"], colorscheme: ["#d9534f", "#428bca"],
+         symbols: ["icons/school.svg", "icons/shop.svg"] })
+```
+
+### Zoom gates: `chartupper` and `chartlower`
+
+`style.chartupper` / `style.chartlower` (`layerupper` / `layerlower` when unset) take a scale `"1:N"`. The
+theme is **hidden when zoomed out beyond `chartupper`** (the scale denominator is above N) and **hidden when
+zoomed in to `chartlower` or closer** (the scale denominator is at or below N). So `chartlower: "1:20000"`
+shows the layer only while the view is zoomed out past 1:20000, and `chartupper: "1:20000"` only from there on
+in. The scale is flat's, about `442913385 / 2^z` for the zoom `z` you give `.view()` on a Mercator map:
+
+| zoom | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 |
+|---|---|---|---|---|---|---|---|---|
+| scale 1: | 432533 | 216266 | 108133 | 54067 | 27033 | 13517 | 6758 | 3379 |
+
+`featureupper`/`featurelower` gate FEATURE themes the same way, `glowupper`/`glowlower` the glow halo.
+
+### Aggregation grid and symbol size
+
+`AGGREGATE` groups items into grid cells. The cell size is read, first match wins, from:
+
+1. `aggregation` (flat's alias `aggregationscale`): scale/width pairs, e.g. `["1:1", "3px", "1:500000", "1px"]`,
+   the width of the last pair for which the view is zoomed out past `1:N` (the example gives 3 px, and 1 px once
+   the view is zoomed out past 1:500000); `"Npx"` is screen pixels, a bare number meters
+2. `gridwidthpx`: screen pixels, constant over zoom (the recommended spelling for a fixed cell)
+3. `gridwidth: "Npx"`: the same, as a string
+4. `gridwidth: N` (a bare number): meters, the same cells at every zoom
+5. none of them: no grid, items stay at their positions
+
+With `CATEGORICAL|COUNT` and no size field the size of a symbol follows the number of records in its cell:
+radius = `15 px × scale × (count / normalsizevalue)^(1/sizepow)`, scaled with the zoom (`objectscaling`) and
+clamped to a minimum and maximum radius.
+`normalsizevalue` is the count drawn at normal size, the dataset's maximum when unset. A `normalsizevalue` of
+`30` therefore draws a single-record cell at 1/30 of the normal radius: pick it near the biggest cell you expect.
+
+### Basemaps (`mapType`)
+
+`mapType` is resolved in this order; a name that matches nothing falls back to the last two rules, so an
+unknown flat name such as `VT_TONER_LITE` draws CARTO Positron:
+
+| `mapType` | style |
+|---|---|
+| `ArcGIS - Topo` (`terrain`), `ArcGIS - Light Gray Base`, `ArcGIS - Ocean Basemap`, `ArcGIS - Hillshade` | Esri raster tiles |
+| `CARTO - Voyager` (`VT_VOYAGER`), `CARTO - Voyager (no labels)` (`VT_VOYAGER_LIGHT`), `CARTO - Positron (no labels)`, `CARTO - Dark Matter (no labels)` | CARTO vector styles |
+| `OpenFreeMap - Liberty`, `OpenFreeMap - Bright`, `OpenFreeMap - Positron` | OpenFreeMap vector styles |
+| any name containing `dark`, `black`, `night` or `matter` | CARTO Dark Matter |
+| everything else | CARTO Positron |
+
+### Adding and replacing themes at runtime
+
+`ixmaps.map().add(theme, "replace")` adds the theme the first time and swaps it on later calls, matched by
+the theme id, `style.name` or `meta.name`. Give the theme a `name` in `.meta()`: the name passed to
+`ixmaps.layer("name", …)` is not the id, and without one `"replace"` cannot find the old theme and adds a second. `ixmaps.map().remove(id)` removes it.
+
+### Text on labels
+
+`CHART|LABEL` (with `TEXTONLY` for the text alone) writes the item's value. A text field bound as the *value*
+reads as 0, as in flat, and shows nothing visible; the console says so once. To show a text, as in flat, keep a
+numeric `value` (or `size`) binding and name the text field in `style.valuefield`, or `"$title$"` for the
+`title` binding:
+
+```js
+.binding({ geo: "geometry", value: "count" })
+.type("CHART|LABEL|TEXTONLY|VALUES")
+.style({ valuefield: "name" })
+```
+
+With `CATEGORICAL` the value field holds the categories and `valuefield` names the text. The text is drawn as a
+single-color glyph with a halo, so an emoji comes out as a monochrome silhouette (seen in a headless Chromium
+test): use image symbols (see Symbols) for colored icons.
+
+### Runtime filtering
+
+A theme's records can be filtered in place, without redefining it, with flat's `changeThemeStyle`:
+
+```js
+ixmaps.changeThemeStyle("mytheme", 'filter:WHERE "type" = "school"', "set");
+ixmaps.changeThemeStyle("mytheme", "filter", "remove");
+```
+
+The same through the handles, `ixmaps.map().changeThemeStyle(id, style, flag)` and
+`ixmaps.map().theme(id).changeStyle(style, flag)`; with `null` as the id every theme but the FEATURE ones is
+changed. The expression is flat's filter grammar: `WHERE field op value` clauses joined by `AND` with `=`, `!=`,
+`<>`, `<`, `>`, `<=`, `>=`, `BETWEEN … AND …`, `IN (…)`, `LIKE` and `NOT` (see `test/unit/filter.test.mjs`).
+(`npm run runtime` in `test/` checks these calls in a browser.)
+
+### Porting a flat page
+
+How the calls of a flat page map to gl; "tested" means `test/runtime.mjs` runs it in a browser.
+
+| flat | gl |
+|---|---|
+| `ixmaps.Map(div, opts, function (map) { … })` | the same; the callback gets the map builder (`view`, `options`, `layer`, `on`, …) |
+| `var myMap = ixmaps.Map(div, opts).view(…)`, `myMap.then(map => …)` | the same, `myMap` is the builder and a thenable |
+| `myMap.layer("name").data(…)…define()` | the same, before and after the map is built (tested) |
+| `myMap.layer(theme)`, `myMap.layer(theme, "direct")` after the map is built | the same (tested); up to v0.2.33 these silently added nothing |
+| `ixmaps.map().layer(theme)`, `ixmaps.map().add(theme, "replace")` | the same (tested) |
+| `ixmaps.changeThemeStyle(id, 'filter:…', "set")` | the same (tested), see Runtime filtering |
+| `map.getBounds()` | `ixmaps.map().getBounds()`, from v0.2.33 |
+| `map.on(event, fn)` | `map.on` / `map.off`, see Map events |
+| `ixmaps.hideTheme(id)` / `ixmaps.showTheme(id)` | not provided: `ixmaps.map().theme(id).hide()` / `.show()` or `ixmaps.map().setThemeVisible(id, bool)` |
+| `ixmaps.flyTo(…)` | not provided: `ixmaps.map().view([lat, lng], zoom)` |
+
+### `CHART|USER` draw function
+
+`style.userdraw` names a function (`ixmaps[name]`, or a dotted path on `window`). It is called as
+`fn(document, opt)` for each chart, after an optional `name_init(document, {target, theme})` once per draw.
+`opt` holds `target` (the SVG group to draw into), `theme`, `value`, `values`, `size`, `maxSize`, `color`,
+`class`, `flag`, `ccolor`, `item` (`{szColor, szLabel, szTitle, nCount, nSize}`) and `dbRecord` (the item's data
+record, also the place to read the category). `size` is in flat's chart units, `maxSize` (300) being the
+normal radius: one unit is `15 px × scale × zoom factor / 300`. The chart is drawn around 0,0.
+
+### Headless, CI and offline
+
+A headless Chromium has no GPU: start it with `--use-gl=swiftshader --enable-unsafe-swiftshader
+--ignore-gpu-blocklist`. deck.gl then logs "GPU stall due to ReadPixels", which is harmless. The engine loads
+`maplibre-gl@6.11.2` (module and css) and `deck.gl@9.4.0` and `mustache@4.2.0` from unpkg, `data.js` from
+jsDelivr (`gh/gjrichter/data.js`), and on demand `d3-array@3.2.4` and `d3-contour@4.0.2` (jsDelivr) and the
+`ixmaps-grammar` validator; mirror these to run offline. Page-level script and data URLs are not
+configurable yet.
+
 ## Quick start
 
 Load the engine from jsDelivr, pinned to a release tag (or `@main` for the latest commit):
 
 ```html
-<script src="https://cdn.jsdelivr.net/gh/gjrichter/ixmaps-gl@v0.2.33/ixmaps-gl.js"></script>
+<script src="https://cdn.jsdelivr.net/gh/gjrichter/ixmaps-gl@v0.2.34/ixmaps-gl.js"></script>
 ```
 
 or from unpkg, the npm package [`ixmaps-gl`](https://www.npmjs.com/package/ixmaps-gl)
@@ -342,13 +482,13 @@ or from unpkg, the npm package [`ixmaps-gl`](https://www.npmjs.com/package/ixmap
 browser script, which defines the global `ixmaps`):
 
 ```html
-<script src="https://unpkg.com/ixmaps-gl@0.2.33/ixmaps-gl.js"></script>
+<script src="https://unpkg.com/ixmaps-gl@0.2.34/ixmaps-gl.js"></script>
 ```
 
 or use a local copy (`<script src="ixmaps-gl.js"></script>`). A minimal page:
 
 ```html
-<script src="https://cdn.jsdelivr.net/gh/gjrichter/ixmaps-gl@v0.2.33/ixmaps-gl.js"></script>
+<script src="https://cdn.jsdelivr.net/gh/gjrichter/ixmaps-gl@v0.2.34/ixmaps-gl.js"></script>
 <div id="map_div" style="position:absolute;inset:0;"></div>
 
 <script>

package/ixmaps-gl.js

@@ -100,7 +100,7 @@
   // ---------------------------------------------------------------
   // this engine's release (= package.json "version", checked by
   // test/unit/version.test.mjs); ixmaps.glVersion, and logged once at start
-  const IXMAPS_GL_VERSION = '0.2.33';
+  const IXMAPS_GL_VERSION = '0.2.34';
 
   const LIB_URLS = {
     // Bumped 3.6.2 -> 5.x (2026-09-21, globe-projection compat fix): native
@@ -7628,7 +7628,12 @@ self.onmessage = e => {
           // object form (a pre-built LayerBuilder, e.g. from the global
           // ixmaps.layer(name, cb) factory): existing semantics, chain
           // back on the MAP for further .layer(a).layer(b) calls.
-          builder.layer(nameOrBuilder);
+          // Once the map is built build() has consumed its queue, so queuing
+          // here would add nothing, silently: define the theme on the live
+          // map instead (flat's runtime overlay: myMap.layer(theme, "direct"),
+          // the second argument is accepted and not needed)
+          if (resolvedApi) resolvedApi.layer(nameOrBuilder);
+          else builder.layer(nameOrBuilder);
           return promise;
         }
         const lb = new LayerBuilder(nameOrBuilder);
@@ -17958,6 +17963,24 @@ self.onmessage = e => {
     //    the item color (stroke font/7, opacity 0.5).
     // Both moved by the chart position (flatChartAlignOffset). The text is
     // the hover target of TEXTONLY, the box of LABEL.
+    // A text field bound as the LABEL's value scans to 0 (flat's __scanValue), so the labels are drawn at the smallest size
+    // with the text "0" — as flat skips such items, nothing visible, and no message. Say how to show a text: flat's
+    // style.valuefield (or "$title$"), with a numeric value or size binding. CATEGORICAL values are categories, not numbers.
+    _warnTextValue(combined) {
+      // looked at once per theme (this runs on every redraw): the first record with a value
+      if (this._checkedTextValue || this.style.valuefield || this.flags.has('CATEGORICAL') || !this.binding.value) return;
+      let sample;
+      for (const d of combined) {
+        const v = d.properties.raw && d.properties.raw[this.binding.value];
+        if (v != null && String(v).trim() !== '') { sample = v; break; }
+      }
+      if (sample === undefined) return;
+      this._checkedTextValue = true;
+      if (!isNaN(scanValue(sample))) return;
+      console.warn(`[ixmaps-gl] theme "${this.name}": LABEL value field "${this.binding.value}" holds text ("${String(sample).slice(0, 20)}"), ` +
+        'which reads as 0 — as in flat the labels are not visible. To show a text keep a numeric value (or size) binding ' +
+        'and name the text field in style.valuefield (or "$title$" for the title).');
+    }
     _buildLabelChartLayers(combined, zoom, liveZoom, sizeValueOf) {
       const textOnly = this.flags.has('TEXTONLY');
       const showValues = this.flags.has('VALUES') && !valuesHiddenByScale(this.style, zoom);
@@ -17972,6 +17995,7 @@ self.onmessage = e => {
       const textOf = props => flatValueText(props.counts ? this._categoryValueRecord(dominant(props.counts)) : props.raw,
         this.binding.title && props.raw ? props.raw[this.binding.title] : undefined, valueOf(props), this.style, this.flags, opts);
 
+      this._warnTextValue(combined);
       if (textOnly) {
         const textRgb = textOverride ? hexOrNamedToRgb(textOverride) : [0, 0, 0];
         const labels = [];
@@ -17981,12 +18005,6 @@ self.onmessage = e => {
           if (!(fontSize > 0)) continue;
           labels.push({ ...d, text: textOf(d.properties), fontSize, halo: itemRgb(d.properties), pixelOffset: alignOf(d) });
         }
-        // a text field read as the value/size scans to 0 (flat's __scanValue), so every label has size 0 and nothing is drawn
-        if (!labels.length && combined.length && !this._warnedNoLabels) {
-          this._warnedNoLabels = true;
-          console.warn(`[ixmaps-gl] theme "${this.name}": LABEL|TEXTONLY drew no labels — the size of all ${combined.length} items is 0. ` +
-            'A non-numeric (text) field bound as value/size reads as 0; bind a numeric size field.');
-        }
         // TextLayer's outlineColor is one per layer: a layer per halo color
         const byHalo = new Map();
         for (const l of labels) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ixmaps-gl",
-  "version": "0.2.33",
+  "version": "0.2.34",
   "description": "MapLibre GL + deck.gl reimplementation of the ixmaps-flat declarative mapping engine",
   "main": "ixmaps-gl.js",
   "browser": "ixmaps-gl.js",