@angular-helpers/openlayers 0.3.0 → 0.5.0

package/README.md

@@ -10,12 +10,14 @@ A modern Angular wrapper for OpenLayers with modular architecture, standalone co
 - **Dual API** - Template for UI, Inputs for data, Services for operations
 - **Tree-shaking** - Unused OpenLayers code is eliminated from your bundle
 - **TypeScript First** - Full type safety with strict mode support
-- **Military Features** - Ellipses, sectors, NATO symbology, and MGRS coordinates
+- **Military Features** - True geodesic precision for ellipses and sectors, NATO symbology, and MGRS coordinates
+- **Proj4 Integration** - Declarative registration of local coordinate systems (like UTM)
+- **WebGL Accelerated** - Mapbox Vector Tiles (MVT) and GPU raster expressions
 
 ## Installation
 
 ```bash
-npm install @angular-helpers/openlayers ol
+pnpm add @angular-helpers/openlayers ol
 ```
 
 ## Quick Start
@@ -30,7 +32,14 @@ import { withLayers } from '@angular-helpers/openlayers/layers';
 import { withControls } from '@angular-helpers/openlayers/controls';
 
 export const appConfig: ApplicationConfig = {
-  providers: [provideOpenLayers(withLayers(), withControls())],
+  providers: [
+    provideOpenLayers(
+      withLayers(),
+      withControls(),
+      // Optional: Register custom coordinate systems with proj4
+      // withProjections(proj4, [{ code: 'EPSG:32630', proj4def: '...', extent: [...] }])
+    ),
+  ],
 };
 ```
 
@@ -49,7 +58,6 @@ import { OlMapService } from '@angular-helpers/openlayers/core';
 
 @Component({
   selector: 'app-map',
-  standalone: true,
   imports: [
     OlMapComponent,
     OlTileLayerComponent,
@@ -176,6 +184,94 @@ 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
+
+Available since `0.4.0` from `@angular-helpers/openlayers/military`.
+
+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.
+
+```typescript
+import { inject, signal } from '@angular/core';
+import { OlMilitaryService } from '@angular-helpers/openlayers/military';
+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-map>
+  `,
+})
+export class MilDemo {
+  private ml = inject(OlMilitaryService);
+  features = signal<Feature[]>([]);
+
+  async ngOnInit() {
+    const ellipse = this.ml.createEllipse({
+      center: [2.17, 41.38],
+      semiMajor: 6_000,
+      semiMinor: 3_000,
+      rotation: Math.PI / 6,
+    });
+    const sector = this.ml.createSector({
+      center: [-0.38, 39.47],
+      radius: 8_000,
+      startAngle: Math.PI / 6,
+      endAngle: Math.PI / 2,
+    });
+    const donut = this.ml.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]);
+  }
+}
+```
+
+### 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
+
+`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:
+
+```bash
+pnpm add milsymbol
+```
+
+```ts
+const symbol = await ml.createMilSymbol({
+  sidc: 'SFGPUCI-----', // friendly infantry, ground unit
+  position: [-3.7, 40.42],
+  size: 36,
+  uniqueDesignation: 'A1',
+});
+```
+
+Three flavors:
+
+- **`createMilSymbol(config)`** — async; lazy-loads on first call.
+- **`createMilSymbolSync(config)`** — sync; throws if `milsymbol` is not loaded yet.
+- **`preloadMilsymbol()`** — fire-and-forget on app init to make the first symbol render synchronous.
+
+The service throws clearly on non-browser environments (`createMilSymbol` requires `window`).
+
 ## Architecture
 
 ### Data vs UI Separation
@@ -206,8 +302,8 @@ import {
   withInteractions,
 } from '@angular-helpers/openlayers/interactions';
 
-// Add military features (~10KB additional)
-import { OlEllipseFeatureComponent, withMilitary } from '@angular-helpers/openlayers/military';
+// Add military features — pure-math helpers + lazy-loaded milsymbol
+import { OlMilitaryService, withMilitary } from '@angular-helpers/openlayers/military';
 ```
 
 ## API Reference