@urban-toolkit/autk-grammar 4.1.1 → 4.3.0

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/dist/index.d.ts CHANGED
@@ -19,6 +19,7 @@ export declare class AutkGrammar {
19
19
  private _computeCache;
20
20
  private _data;
21
21
  private _mapRegistry;
22
+ private _mapLayerIds;
22
23
  private _maps;
23
24
  private _plotRegistry;
24
25
  private _fwdCleanups;
@@ -44,17 +45,27 @@ export declare class AutkGrammar {
44
45
  * and read in a `requestAnimationFrame` callback registered after that call.
45
46
  */
46
47
  get maps(): readonly AutkMap[];
48
+ /**
49
+ * The layer a map of the last {@link run} draws for a table, found by the table's name (a layer's `dataRef`):
50
+ * the map that draws it, and the layer's id in that map, which is its `title`, else its `dataRef`.
51
+ * `undefined` when no map draws the table. When several layers draw it, the last one.
52
+ *
53
+ * @example
54
+ * const layer = grammar.mapLayer('buildings');
55
+ * layer?.map.updateRenderInfo(layer.layerId, { opacity: 0.5 });
56
+ */
57
+ mapLayer(dataRef: string): GrammarMapLayer | undefined;
47
58
  run(spec: UrbanSpec): Promise<void>;
48
59
  /**
49
- * Highlights features on the map layer identified by `layerId`.
60
+ * Highlights features on the map layer that draws the table `dataRef` (see {@link mapLayer}).
50
61
  * If that layer is linked to a plot via `mapRef`, the plot selection is updated too.
51
62
  */
52
- highlightOnMap(layerId: string, featureIds: number[]): void;
63
+ highlightOnMap(dataRef: string, featureIds: number[]): void;
53
64
  /**
54
- * Clears highlighted features on the map layer identified by `layerId`.
65
+ * Clears highlighted features on the map layer that draws the table `dataRef` (see {@link mapLayer}).
55
66
  * If that layer is linked to a plot via `mapRef`, the plot selection is cleared too.
56
67
  */
57
- clearHighlightOnMap(layerId: string): void;
68
+ clearHighlightOnMap(dataRef: string): void;
58
69
  /**
59
70
  * Clears the selection on the plot identified by `plotId` (its dataRef).
60
71
  * If that plot is linked to a map via `mapRef`, the map highlight is cleared too.
@@ -331,6 +342,14 @@ export declare type GrammarEventRecord = {
331
342
  'plot:selection': GrammarPlotSelectionEvent;
332
343
  };
333
344
 
345
+ /** A layer a map of the last run draws, as `AutkGrammar.mapLayer` finds it by its table's name. */
346
+ export declare interface GrammarMapLayer {
347
+ /** The map that draws the layer. */
348
+ map: AutkMap;
349
+ /** The layer's id in that map: its `title`, else its `dataRef`. */
350
+ layerId: string;
351
+ }
352
+
334
353
  export declare interface GrammarPickingEvent {
335
354
  layerId: string;
336
355
  selection: number[];
@@ -370,6 +389,12 @@ export declare interface HeatmatrixPlotSpec extends PlotBase {
370
389
  transform: PlotTransformSpec<'binning-2d'>;
371
390
  }
372
391
 
392
+ /**
393
+ * A color as `#rrggbb`.
394
+ * @pattern ^#[0-9a-fA-F]{6}$
395
+ */
396
+ export declare type HexColor = string;
397
+
373
398
  export declare interface IEngine {
374
399
  run(): Promise<void>;
375
400
  updatedSpec(spec: UrbanSpec): Promise<void>;
@@ -439,6 +464,13 @@ export declare interface JsonDataSourceSpec extends TableSourceBase {
439
464
  geometryColumns?: GeometryColumns;
440
465
  }
441
466
 
467
+ /**
468
+ * A latitude in degrees (WGS84).
469
+ * @minimum -90
470
+ * @maximum 90
471
+ */
472
+ declare type Latitude = number;
473
+
442
474
  /**
443
475
  * Point geometry from two columns holding latitude and longitude.
444
476
  */
@@ -458,6 +490,13 @@ export declare interface LinePlotSpec extends PlotBase {
458
490
  transform: PlotTransformSpec<'reduce-series' | 'binning-events'>;
459
491
  }
460
492
 
493
+ /**
494
+ * A longitude in degrees (WGS84).
495
+ * @minimum -180
496
+ * @maximum 180
497
+ */
498
+ declare type Longitude = number;
499
+
461
500
  /**
462
501
  * Interface for map styles.
463
502
  * @property {Promise<unknown>} resolveMap - Resolves map specification.
@@ -468,18 +507,61 @@ export declare interface MapAdapter {
468
507
  resolveMap(context: unknown, spec: MapSpec, index?: number): Promise<unknown>;
469
508
  }
470
509
 
510
+ export declare type MapLayerIds = Map<string, string>;
511
+
471
512
  /**
472
513
  * One layer drawn by a map.
473
514
  */
474
515
  export declare type MapLayerSpec = {
475
516
  /** Name of the table to draw, as produced by a data source or a compute pass. */
476
517
  dataRef: string;
518
+ /**
519
+ * Name of the layer, shown as its legend's title. It becomes the layer's id in the map, so two layers of one
520
+ * map cannot have the same title, and a title cannot be another layer's `dataRef` in that map. Without it, the
521
+ * layer's id is its `dataRef`. Read by the Autark adapter; the deck.gl adapter ignores it.
522
+ * @minLength 1
523
+ */
524
+ title?: string;
477
525
  /** Layer opacity, from 0 to 1. */
478
526
  opacity?: number;
527
+ /**
528
+ * Color of the layer, as `#rrggbb`. A layer with a color is drawn in it rather than by its `getFnv` value,
529
+ * unless `isColorMap` is `true`. Raster layers are always colored by value. Read by the Autark adapter; the
530
+ * deck.gl adapter ignores it.
531
+ */
532
+ color?: HexColor;
533
+ /**
534
+ * Outline of a polygon layer: its color, as `#rrggbb`, or `false` to draw no outline. Read by the Autark
535
+ * adapter, which outlines polygon layers only; the deck.gl adapter ignores it.
536
+ */
537
+ stroke?: HexColor | false;
538
+ /**
539
+ * Width of the lines of a polylines or roads layer, in the map's planar units (about meters). It replaces
540
+ * the widths a roads layer gives each kind of road. Read by the Autark adapter; the deck.gl adapter ignores it.
541
+ * @exclusiveMinimum 0
542
+ */
543
+ width?: number;
479
544
  /** Color the layer by the value read with `getFnv`. */
480
545
  isColorMap?: boolean;
481
546
  /** Color scheme used when `isColorMap` is set. */
482
547
  colorMapInterpolator?: ColorMapInterpolator;
548
+ /**
549
+ * Value at the middle of a raster layer's color scale: the scale runs from this value less the farthest value's
550
+ * distance to it, to this value plus that distance, so a diverging scheme's middle color marks it. Read by the
551
+ * Autark adapter for raster layers; other layers and the deck.gl adapter ignore it.
552
+ */
553
+ colorMapCenter?: number;
554
+ /**
555
+ * Run a raster layer's color scale from its highest value to its lowest, so the scheme's first color marks the
556
+ * highest value. Read by the Autark adapter for raster layers; other layers and the deck.gl adapter ignore it.
557
+ */
558
+ colorMapReverse?: boolean;
559
+ /**
560
+ * How opaque a raster layer's cells are by value, as autk-map's transfer function: for example
561
+ * `{ opacityMin: 1, opacityMax: 1 }` draws every cell with a value fully opaque. Read by the Autark adapter for
562
+ * raster layers; other layers and the deck.gl adapter ignore it.
563
+ */
564
+ transferFunction?: RasterTransferFunction;
483
565
  /** Legend labels. Read by the deck.gl adapter; the Autark adapter ignores it. */
484
566
  colorMapLabels?: string[];
485
567
  /** Feature ids drawn as picked. Read by the deck.gl adapter; the Autark adapter ignores it. */
@@ -543,7 +625,23 @@ export declare enum NormalizationMode {
543
625
  }
544
626
 
545
627
  /**
546
- * Loads OpenStreetMap data for a named area, from Overpass or from a PBF extract.
628
+ * An area given as a box instead of boundary names. The box is the whole area: no boundary is read.
629
+ */
630
+ export declare interface OsmBoundingBoxArea {
631
+ /**
632
+ * The box as `[west, south, east, north]` in degrees (WGS84), with west less than east and south less than
633
+ * north. A box across the antimeridian is not supported. The Autark adapter cuts each layer to the box, but
634
+ * keeps or drops each building whole.
635
+ */
636
+ bbox: [west: Longitude, south: Latitude, east: Longitude, north: Latitude];
637
+ /** Not with `bbox`. */
638
+ geocodeArea?: undefined;
639
+ /** Not with `bbox`. */
640
+ areas?: undefined;
641
+ }
642
+
643
+ /**
644
+ * Loads OpenStreetMap data for a named area or a box, from Overpass or from a PBF extract.
547
645
  */
548
646
  export declare interface OsmDataSourceSpec extends TableSourceBase {
549
647
  type: 'osm';
@@ -555,13 +653,20 @@ export declare interface OsmDataSourceSpec extends TableSourceBase {
555
653
  dropOsmTable?: boolean;
556
654
  layers: Array<LayerType>;
557
655
  };
558
- /** Area to load: the named sub-areas inside a geocoded region. */
559
- queryArea: {
560
- /** Region to geocode, for example a city name. */
561
- geocodeArea: string;
562
- /** Sub-areas inside the region, for example neighborhood names. */
563
- areas: string[];
564
- };
656
+ /** Area to load: sub-areas inside a geocoded region (`geocodeArea` with `areas`), or a box (`bbox`), not both. */
657
+ queryArea: OsmNamedArea | OsmBoundingBoxArea;
658
+ }
659
+
660
+ /**
661
+ * An area named by OpenStreetMap boundaries: sub-areas inside a geocoded region.
662
+ */
663
+ export declare interface OsmNamedArea {
664
+ /** Region to geocode, for example a city name. */
665
+ geocodeArea: string;
666
+ /** Sub-areas inside the region, for example neighborhood names. */
667
+ areas: string[];
668
+ /** Not with `geocodeArea` and `areas`. */
669
+ bbox?: undefined;
565
670
  }
566
671
 
567
672
  /** Parallel coordinates over the plotted columns. */
@@ -601,7 +706,7 @@ export declare interface PlotBase {
601
706
  top: number;
602
707
  bottom: number;
603
708
  };
604
- /** Layer id of a map this plot links its selection to. */
709
+ /** `dataRef` of the map layer this plot links its selection to. */
605
710
  mapRef?: string;
606
711
  }
607
712
 
@@ -632,6 +737,36 @@ export declare interface PlotTransformSpec<P extends PlotTransformPreset = PlotT
632
737
  options?: Record<string, unknown>;
633
738
  }
634
739
 
740
+ /**
741
+ * How opaque a raster layer's cells are by value: autk-map's transfer function. A cell with no value is clear.
742
+ */
743
+ export declare type RasterTransferFunction = {
744
+ /**
745
+ * `far-zero`: cells farther from `zeroCenter` are more opaque (autk-map's default). `near-zero`: cells closer to
746
+ * `zeroCenter` are more opaque. `linear`: opacity grows from the lowest value to the highest.
747
+ */
748
+ mode?: 'near-zero' | 'far-zero' | 'linear';
749
+ /**
750
+ * Lowest opacity, from 0 to 1. Defaults to 0.
751
+ * @minimum 0
752
+ * @maximum 1
753
+ */
754
+ opacityMin?: number;
755
+ /**
756
+ * Highest opacity, from 0 to 1. Defaults to 1.
757
+ * @minimum 0
758
+ * @maximum 1
759
+ */
760
+ opacityMax?: number;
761
+ /**
762
+ * Exponent applied to a cell's place between the lowest and highest opacity. Defaults to 1.
763
+ * @exclusiveMinimum 0
764
+ */
765
+ gamma?: number;
766
+ /** Value the `far-zero` and `near-zero` modes measure from. Defaults to 0. */
767
+ zeroCenter?: number;
768
+ };
769
+
635
770
  /**
636
771
  * Turns a compute pass into the parameters of one GPU dispatch. Pure: it reads `layers` and runs
637
772
  * nothing. With `iterate: 'all'`, pass the feature index as `iterateIndex` for each dispatch (see
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@urban-toolkit/autk-grammar",
3
- "version": "4.1.1",
3
+ "version": "4.3.0",
4
4
  "description": "A declarative grammar for urban visual analytics, built on Autark",
5
5
  "license": "MIT",
6
6
  "author": "Gustavo Moreira",
@@ -56,10 +56,10 @@
56
56
  },
57
57
  "dependencies": {
58
58
  "@types/geojson": "^7946.0.16",
59
- "@urban-toolkit/autk-compute": "^4.1.0",
60
- "@urban-toolkit/autk-core": "^4.1.0",
61
- "@urban-toolkit/autk-db": "^4.1.0",
62
- "@urban-toolkit/autk-map": "^4.1.0",
63
- "@urban-toolkit/autk-plot": "^4.1.0"
59
+ "@urban-toolkit/autk-compute": "^4.1.1",
60
+ "@urban-toolkit/autk-core": "^4.1.1",
61
+ "@urban-toolkit/autk-db": "^4.1.1",
62
+ "@urban-toolkit/autk-map": "^4.1.1",
63
+ "@urban-toolkit/autk-plot": "^4.1.1"
64
64
  }
65
65
  }