@angular-helpers/openlayers 0.5.0 → 0.5.1

package/README.md

@@ -184,87 +184,150 @@ const handle = popups.openComponent({
 
 `open` is idempotent by `id` and updates the existing overlay in place. `openComponent` always recreates the `ComponentRef` on a repeated id and disposes the previous one (`appRef.detachView` + `ref.destroy`) to avoid CD leaks. Calls made before the map is ready are queued and replayed on `OlMapService.onReady`.
 
-## Military symbology
+## WebGL Layers — GPU-accelerated rendering
 
-Available since `0.4.0` from `@angular-helpers/openlayers/military`.
+Available since `0.3.0` from `@angular-helpers/openlayers/layers`.
+
+WebGL layers render directly on the GPU, making them perfect for extremely heavy tile configurations (with real-time styling expressions) and massive coordinate datasets (10,000+ vector points).
+
+### `<ol-webgl-tile-layer>` — Raster style manipulation
+
+Renders tile layers (OSM, XYZ, MVT) via WebGL. Supports the dynamic application of WebGL tile styles (raster expressions) for dynamic, GPU-powered adjustments like brightness, contrast, saturation, and gamma.
+
+```html
+<ol-webgl-tile-layer
+  id="satellite-webgl"
+  source="xyz"
+  [url]="'https://server.arcgisonline.com/ArcGIS/rest/services/World_Imagery/MapServer/tile/{z}/{y}/{x}'"
+  [tileStyle]="{
+    brightness: 0.1,
+    contrast: 0.2,
+    saturation: -0.5
+  }"
+/>
+```
+
+### `<ol-webgl-vector-layer>` — Smooth massive datasets (10k+ features)
+
+Renders points, lines, and polygons using WebGL 2. For peak performance, hit detection is disabled by default, and styling must be declared using `FlatStyleLike` expressions rather than standard `ol/style/Style` instances.
+
+```html
+<ol-webgl-vector-layer
+  id="massive-points"
+  [features]="densePoints()"
+  [flatStyle]="{
+    'circle-radius': 6,
+    'circle-fill-color': '#10b981',
+    'stroke-color': '#334155',
+    'stroke-width': 1
+  }"
+  [disableHitDetection]="true"
+/>
+```
+
+Rigorous cleanup guarantees that WebGL contexts, framebuffers, and active buffers are fully released on destroy (`layer.dispose()`), preventing GPU leaks.
+
+## Geodesic Geometry Helpers
 
-Three pure-math geometry helpers (no extra deps) plus a NATO MIL-STD-2525 symbol helper backed by the optional [`milsymbol`](https://github.com/spatialillusions/milsymbol) peer dependency.
+Available from `@angular-helpers/openlayers/core` via `OlGeometryService`.
+
+Approximates standard shapes in metric space using true geodesic calculations (`Vincenty`'s formulae via `ol/sphere`). This means your shapes remain mathematically accurate and visually consistent (without map projection scale distortion) across massive global distances.
 
 ```typescript
-import { inject, signal } from '@angular/core';
-import { OlMilitaryService } from '@angular-helpers/openlayers/military';
+import { inject, Component, signal } from '@angular/core';
+import { OlGeometryService } from '@angular-helpers/openlayers/core';
 import type { Feature } from '@angular-helpers/openlayers/core';
 
 @Component({
-  // …
   imports: [OlMapComponent, OlVectorLayerComponent],
   template: `
     <ol-map [center]="[2.17, 41.38]" [zoom]="8">
       <ol-tile-layer id="osm" source="osm" />
-      <ol-vector-layer id="military" [features]="features()" [zIndex]="10" />
+      <ol-vector-layer id="shapes" [features]="features()" />
     </ol-map>
   `,
 })
-export class MilDemo {
-  private ml = inject(OlMilitaryService);
+export class GeodesicDemo {
+  private geomSvc = inject(OlGeometryService);
   features = signal<Feature[]>([]);
 
-  async ngOnInit() {
-    const ellipse = this.ml.createEllipse({
+  ngOnInit() {
+    const ellipse = this.geomSvc.createEllipse({
       center: [2.17, 41.38],
       semiMajor: 6_000,
       semiMinor: 3_000,
       rotation: Math.PI / 6,
     });
-    const sector = this.ml.createSector({
+    const sector = this.geomSvc.createSector({
       center: [-0.38, 39.47],
       radius: 8_000,
       startAngle: Math.PI / 6,
       endAngle: Math.PI / 2,
     });
-    const donut = this.ml.createDonut({
+    const donut = this.geomSvc.createDonut({
       center: [-5.99, 37.39],
       innerRadius: 5_000,
       outerRadius: 10_000,
     });
-    const symbol = await this.ml.createMilSymbol({
-      sidc: 'SFGPUCI-----',
-      position: [-3.7, 40.42],
-      size: 36,
-    });
-    this.features.set([ellipse, sector, donut, symbol]);
+    this.features.set([ellipse, sector, donut]);
   }
 }
 ```
 
-### Geometry helpers
-
 | Method                  | Output             | Notes                                                                                                                  |
 | ----------------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------- |
 | `createEllipse(config)` | `Feature<Polygon>` | Optional `rotation` in radians, configurable `segments` (default 64)                                                   |
 | `createSector(config)`  | `Feature<Polygon>` | Pie-slice (apex-arc-apex). `startAngle < endAngle ≤ start + 2π`                                                        |
 | `createDonut(config)`   | `Feature<Polygon>` | Two rings: outer CCW, inner CW (right-hand rule). Renders as an annular band with the basemap visible through the hole |
 
-Coordinates are emitted in `EPSG:4326` (lon/lat) using true geodesic calculations (`Vincenty`'s formulae via `ol/sphere`). This means your shapes remain mathematically accurate and visually consistent (without scale distortion) across massive global distances, fulfilling military precision requirements.
+---
 
-### MIL-STD-2525 symbols
+## Military Symbology & Tactical Graphics
 
-`createMilSymbol` lazy-loads `milsymbol` on first use and returns a `Feature<Point>` with style metadata (`feature.style.icon`) so the vector layer renders it as an `ol/style/Icon`. The library is declared as an **optional peer dependency** — install it only if you use this helper:
+Available since `0.4.0` from `@angular-helpers/openlayers/military`.
 
-```bash
-pnpm add milsymbol
+Exposes NATO MIL-STD-2525 symbol rendering backed by the optional [`milsymbol`](https://github.com/spatialillusions/milsymbol) peer dependency, plus tactical military graphic components (frontlines, attack vectors).
+
+### MIL-STD-2525 Point Symbology (`OlMilitaryService`)
+
+Lazy-loads the heavy `milsymbol` package dynamically on demand, returning a styled `Feature<Point>` so the vector layer renders it natively.
+
+```typescript
+import { inject, Component, signal } from '@angular/core';
+import { OlMilitaryService } from '@angular-helpers/openlayers/military';
+import type { Feature } from '@angular-helpers/openlayers/core';
+
+@Component({
+  imports: [OlMapComponent, OlVectorLayerComponent],
+  providers: [OlMilitaryService],
+  template: `
+    <ol-map [center]="[-3.7, 40.42]" [zoom]="8">
+      <ol-vector-layer id="military" [features]="features()" />
+    </ol-map>
+  `,
+})
+export class MilDemo {
+  private milSvc = inject(OlMilitaryService);
+  features = signal<Feature[]>([]);
+
+  async ngOnInit() {
+    const symbol = await this.milSvc.createMilSymbol({
+      sidc: 'SFGPUCI-----', // Friendly Infantry Unit
+      position: [-3.7, 40.42],
+      size: 36,
+    });
+    this.features.set([symbol]);
+  }
+}
 ```
 
-```ts
-const symbol = await ml.createMilSymbol({
-  sidc: 'SFGPUCI-----', // friendly infantry, ground unit
-  position: [-3.7, 40.42],
-  size: 36,
-  uniqueDesignation: 'A1',
-});
+Install the optional peer dependency if utilizing NATO symbology:
+
+```bash
+pnpm add milsymbol
 ```
 
-Three flavors:
+Three execution strategies:
 
 - **`createMilSymbol(config)`** — async; lazy-loads on first call.
 - **`createMilSymbolSync(config)`** — sync; throws if `milsymbol` is not loaded yet.
@@ -272,6 +335,28 @@ Three flavors:
 
 The service throws clearly on non-browser environments (`createMilSymbol` requires `window`).
 
+### Tactical Graphics (`OlTacticalGraphicsService`)
+
+Builds advanced multi-point military tactical graphic features (frontlines with directional teeth, attack arrow coordinates) and provides custom styles.
+
+```typescript
+import { OlTacticalGraphicsService } from '@angular-helpers/openlayers/military';
+
+const tacticalSvc = inject(OlTacticalGraphicsService);
+
+// Create a frontline graphic
+const frontline = tacticalSvc.createFrontLine(
+  [
+    [2.1, 41.3],
+    [2.2, 41.4],
+  ],
+  'friendly',
+);
+
+// Apply specialized style for frontline teeth
+const frontlineStyle = tacticalSvc.createFrontLineStyle('#4f46e5', 'friendly');
+```
+
 ## Architecture
 
 ### Data vs UI Separation

package/core/README.md

@@ -0,0 +1,43 @@
+# @angular-helpers/openlayers/core
+
+Core library for Angular bindings to OpenLayers.
+Provides essential models, services, and the base `<ol-map>` component.
+
+## Installation
+
+\`\`\`bash
+npm install @angular-helpers/openlayers
+\`\`\`
+
+## Core Services & Components
+
+- \`OlMapComponent\`: The root map component that manages the core OpenLayers `Map` instance.
+- \`OlMapService\`: A service to retrieve and manage the map instance across child components.
+- \`OlLayerService\`: Manages map layers dynamically.
+- \`OlZoneHelper\`: Optimizes Angular change detection around OpenLayers events.
+
+## Usage
+
+\`\`\`typescript
+import { Component } from '@angular/core';
+import { OlMapComponent } from '@angular-helpers/openlayers';
+import { OlTileLayerComponent } from '@angular-helpers/openlayers/layers';
+
+@Component({
+selector: 'app-map-demo',
+imports: [OlMapComponent, OlTileLayerComponent],
+template: \`
+<ol-map [center]="[0, 0]" [zoom]="4" class="map-container">
+<ol-tile-layer source="osm"></ol-tile-layer>
+</ol-map>
+\`,
+styles: [\`
+.map-container {
+width: 100%;
+height: 400px;
+display: block;
+}
+\`]
+})
+export class MapDemoComponent {}
+\`\`\`

package/fesm2022/angular-helpers-openlayers-core.mjs

@@ -1,9 +1,12 @@
 import * as i0 from '@angular/core';
-import { inject, NgZone, Injectable, signal, DestroyRef, input, output, viewChild, afterNextRender, effect, ChangeDetectionStrategy, Component, makeEnvironmentProviders, ENVIRONMENT_INITIALIZER } from '@angular/core';
+import { inject, NgZone, Injectable, signal, DestroyRef, input, output, viewChild, afterNextRender, effect, ChangeDetectionStrategy, Component, computed, resource, makeEnvironmentProviders, ENVIRONMENT_INITIALIZER } from '@angular/core';
 import OLMap from 'ol/Map';
 import View from 'ol/View';
 import { fromLonLat, toLonLat, get } from 'ol/proj';
 import { offset } from 'ol/sphere';
+import GeoJSON from 'ol/format/GeoJSON';
+import FeatureClass from 'ol/Feature';
+import { Point, LineString, Polygon } from 'ol/geom';
 import { register } from 'ol/proj/proj4';
 
 // ZoneHelperService - Handles NgZone compatibility for zoneless mode
@@ -430,6 +433,216 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.13", ngImpo
                 }]
         }] });
 
+/**
+ * Service for orchestrating time-series animations in OpenLayers.
+ * Exposes a reactive currentTime signal that updates outside the Angular zone
+ * via requestAnimationFrame, ensuring 60FPS WebGL animations without triggering
+ * global change detection.
+ */
+class OlTimeService {
+    zoneHelper = inject(OlZoneHelper);
+    timeSignal = signal(Date.now(), ...(ngDevMode ? [{ debugName: "timeSignal" }] : /* istanbul ignore next */ []));
+    playingSignal = signal(false, ...(ngDevMode ? [{ debugName: "playingSignal" }] : /* istanbul ignore next */ []));
+    speedSignal = signal(1, ...(ngDevMode ? [{ debugName: "speedSignal" }] : /* istanbul ignore next */ []));
+    animationFrameId = null;
+    lastTick = 0;
+    currentTime = computed(() => this.timeSignal(), ...(ngDevMode ? [{ debugName: "currentTime" }] : /* istanbul ignore next */ []));
+    isPlaying = computed(() => this.playingSignal(), ...(ngDevMode ? [{ debugName: "isPlaying" }] : /* istanbul ignore next */ []));
+    speed = computed(() => this.speedSignal(), ...(ngDevMode ? [{ debugName: "speed" }] : /* istanbul ignore next */ []));
+    /**
+     * Sets the current time manually.
+     * @param time Epoch timestamp in milliseconds
+     */
+    setTime(time) {
+        this.timeSignal.set(time);
+    }
+    /**
+     * Sets the playback speed multiplier.
+     * @param speed Multiplier (e.g. 1 = real time, 60 = 1 minute per second)
+     */
+    setSpeed(speed) {
+        this.speedSignal.set(speed);
+    }
+    /**
+     * Starts the time animation loop.
+     */
+    play() {
+        if (this.playingSignal())
+            return;
+        this.playingSignal.set(true);
+        this.lastTick = performance.now();
+        this.zoneHelper.runOutsideAngular(() => {
+            const loop = (now) => {
+                if (!this.playingSignal())
+                    return;
+                const delta = now - this.lastTick;
+                this.lastTick = now;
+                // Advance time based on delta and speed multiplier
+                const advance = delta * this.speedSignal();
+                this.timeSignal.update((t) => t + advance);
+                this.animationFrameId = requestAnimationFrame(loop);
+            };
+            this.animationFrameId = requestAnimationFrame(loop);
+        });
+    }
+    /**
+     * Pauses the time animation loop.
+     */
+    pause() {
+        this.playingSignal.set(false);
+        if (this.animationFrameId !== null) {
+            cancelAnimationFrame(this.animationFrameId);
+            this.animationFrameId = null;
+        }
+    }
+    /**
+     * Stops the animation and resets to a specific time.
+     */
+    stop(resetTime = Date.now()) {
+        this.pause();
+        this.setTime(resetTime);
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.13", ngImport: i0, type: OlTimeService, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.13", ngImport: i0, type: OlTimeService, providedIn: 'root' });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.13", ngImport: i0, type: OlTimeService, decorators: [{
+            type: Injectable,
+            args: [{ providedIn: 'root' }]
+        }] });
+
+// Feature conversion utilities for OpenLayers interactions
+/**
+ * Converts an OpenLayers feature to the internal Feature format.
+ * Handles coordinate extraction and geometry type mapping.
+ *
+ * @param olFeature - The OpenLayers feature to convert
+ * @returns The converted Feature with normalized structure
+ */
+function olFeatureToFeature(olFeature) {
+    // Unwrap spider features
+    const spiderFeature = olFeature.get('spider-feature');
+    if (spiderFeature) {
+        return olFeatureToFeature(spiderFeature);
+    }
+    // Unwrap single-item clusters
+    const clusterFeatures = olFeature.get('features');
+    if (Array.isArray(clusterFeatures) && clusterFeatures.length === 1) {
+        return olFeatureToFeature(clusterFeatures[0]);
+    }
+    const geometry = olFeature.getGeometry();
+    const geomType = geometry?.getType() ?? 'Point';
+    // Convert coordinates based on geometry type
+    let coordinates;
+    if (geomType === 'Circle') {
+        // ol/geom/Circle has no getCoordinates() — use getCenter() instead
+        const circle = geometry;
+        coordinates = circle.getCenter();
+    }
+    else {
+        // oxlint-disable-next-line no-explicit-any
+        const olCoords = geometry.getCoordinates();
+        if (Array.isArray(olCoords) && Array.isArray(olCoords[0])) {
+            // Multi-coordinate structures (LineString, Polygon, etc.)
+            coordinates = olCoords;
+        }
+        else {
+            // Single point
+            coordinates = olCoords;
+        }
+    }
+    return {
+        id: olFeature.getId()?.toString() ?? `feature-${Math.random().toString(36).slice(2)}`,
+        geometry: {
+            type: geomType,
+            coordinates,
+        },
+        properties: olFeature.getProperties(),
+    };
+}
+/**
+ * Converts an internal Feature to an OpenLayers feature.
+ */
+function featureToOlFeature(feature) {
+    const geom = feature.geometry;
+    let geometry;
+    if (!geom.coordinates) {
+        geometry = new Point([0, 0]);
+    }
+    else if (geom.type === 'Point') {
+        const coords = geom.coordinates;
+        geometry = new Point(fromLonLat(coords));
+    }
+    else if (geom.type === 'LineString') {
+        const coords = geom.coordinates.map((c) => fromLonLat(c));
+        geometry = new LineString(coords);
+    }
+    else if (geom.type === 'Polygon') {
+        const rings = geom.coordinates.map((ring) => ring.map((c) => fromLonLat(c)));
+        geometry = new Polygon(rings);
+    }
+    else {
+        geometry = new Point([0, 0]);
+    }
+    // Create OL Feature
+    // Note: we must avoid passing 'geometry' as a plain object to OLFeature constructor,
+    // so we pass the object properties without it, then set geometry explicitly.
+    const props = { ...feature.properties };
+    delete props['geometry']; // Just in case
+    const olFeature = new FeatureClass(props);
+    olFeature.setGeometry(geometry);
+    olFeature.setId(feature.id);
+    return olFeature;
+}
+
+/**
+ * Creates an Angular resource for fetching and decoding GeoJSON into OpenLayers Features.
+ * Must be called in an injection context.
+ *
+ * @param url The URL signal or string to fetch data from
+ * @param options Additional vector resource options
+ * @returns An Angular Resource containing an array of parsed Features
+ */
+function createVectorResource(url, options) {
+    return resource({
+        loader: async ({ abortSignal }) => {
+            const fetchUrl = url();
+            if (!fetchUrl)
+                return [];
+            const cacheKey = 'ol-vector-cache-v1';
+            const isBrowser = typeof caches !== 'undefined';
+            let response;
+            let cache;
+            if (isBrowser) {
+                cache = await caches.open(cacheKey);
+                const cachedResponse = await cache.match(fetchUrl);
+                if (cachedResponse) {
+                    response = cachedResponse;
+                }
+            }
+            if (!response) {
+                response = await fetch(fetchUrl, {
+                    ...options?.fetchOptions,
+                    signal: abortSignal,
+                });
+                if (!response.ok) {
+                    throw new Error(`Failed to fetch vector data: ${response.statusText}`);
+                }
+                if (isBrowser && cache) {
+                    await cache.put(fetchUrl, response.clone());
+                }
+            }
+            // We process the text since GeoJSON readFeatures accepts string or object.
+            // Doing text() might be slightly faster before passing to OL's parser.
+            const data = await response.text();
+            const format = new GeoJSON();
+            // We parse the GeoJSON string into OpenLayers features.
+            const olFeatures = format.readFeatures(data);
+            // Convert to our generic Feature interface expected by OlVectorLayer
+            return olFeatures.map((f) => olFeatureToFeature(f));
+        },
+    });
+}
+
 // Provider functions
 function provideOpenLayers(...features) {
     return makeEnvironmentProviders([
@@ -478,4 +691,4 @@ function withProjections(proj4, definitions) {
  * Generated bundle index. Do not edit.
  */
 
-export { OlGeometryService, OlMapComponent, OlMapService, OlZoneHelper, provideOpenLayers, withProjections };
+export { OlGeometryService, OlMapComponent, OlMapService, OlTimeService, OlZoneHelper, createVectorResource, featureToOlFeature, olFeatureToFeature, provideOpenLayers, withProjections };