geoai 1.0.3 → 1.0.5

package/CHANGELOG.md

@@ -7,24 +7,36 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.0.5] - 2026-07-15
+
+### Added
+- WMS map provider with OGC GetMap support (EPSG:3857 bbox, WMS 1.1.1 / 1.3.0)
+- `examples/06-wms-quickstart` — NRW orthophotos (`nw_dop_rgb`), draw-to-detect, NRW geocoder
+- Interactive TMS and WMS providers in `live-examples-nextjs` task demos
+- WMS documentation (`wms.mdx`), map-providers table update, and 17 WMS tests (including pipeline inference)
+- Project roadmap (`_docs4devs/ROADMAP.md`) for use-case guides and quantization pipeline backlog
+
 ### Changed
-- Removed OpenCV.js dependency across all AI models for improved performance and reduced bundle size
-- Migrated building-footprint-segmentation and landcover-classification to use d3-contours for contour processing
-- Replaced OpenCV implementations with native JavaScript solutions
+- `live-examples-nextjs` pins `geoai` to local `build/` for WMS/TMS provider development
+
+## [1.0.4] - 2026-07-11
 
 ### Added
-- Tile stitching method to GeoRawImage for improved image handling capabilities
-- GeoJSON output option for landcover classification results
-- Result layer type selector for better visualization control
+- TMS map provider with `{z}/{x}/{y}` URL templates and WebMercator/TMS tile schemes
+- `examples/05-tms-quickstart` and TMS / serving-raster-tiles documentation
 
 ### Fixed
-- Mask generation post-processing improvements
-- Multipolygon issues in mask generation
-- Landcover classification mask to polygon conversion accuracy
+- `dts-bundle-generator` config for ESM package type (`build:types` in CI)
+- CI test stability: Geobase tile mocks, ONNX cache cleanup, and zero-shot test isolation
+- Test gist uploads no longer log errors when GitHub credentials are missing or invalid
 
-### Improved
-- Overall library performance with removal of heavy OpenCV dependency
-- Memory usage optimization in geospatial processing tasks
+### Changed
+- Gist uploads in tests are opt-in via `GEOAI_SAVE_GISTS=1`
+
+## [1.0.3] - 2025-08-28
+
+### Fixed
+- Landuse classification vectorisation bug fix
 
 ## [1.0.0-rc.1] - 2024-01-XX
 
@@ -125,12 +137,6 @@ To migrate from the old package:
 
 ## [1.0.1] - 2025-08-28
 
-### Release Candidate
+### Changed
 - Removed OpenCV.js dependency across all AI models for improved performance and reduced bundle size.
 
-
-## [1.0.3] - 2025-08-28
-
-### Release Candidate
-- Landuse classification vectorisation bug fix
-

package/README.md

@@ -40,12 +40,12 @@ You can also use GeoAI directly in the browser via CDN:
 
 #### Unpkg CDN
 ```html
-<script src="https://unpkg.com/geoai@1.0.3/geoai.js"></script>
+<script src="https://unpkg.com/geoai@1.0.5/geoai.js"></script>
 ```
 
 #### jsDelivr CDN
 ```html
-<script src="https://cdn.jsdelivr.net/npm/geoai@1.0.3/geoai.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/geoai@1.0.5/geoai.min.js"></script>
 ```
 
 When using CDN, the library is available globally as `geoai`.
@@ -133,7 +133,7 @@ function MyComponent() {
 ## Features
 
 - **Multiple AI Tasks**: Object detection, segmentation, classification, and more
-- **Map Provider Support**: Geobase, Mapbox, ESRI, and Google Maps
+- **Map Provider Support**: Geobase, Mapbox, ESRI, TMS, and Google Maps
 - **React Integration**: Hooks for easy React integration
 - **TypeScript Support**: Full TypeScript definitions
 - **Web Worker Support**: Run AI models in background threads
@@ -158,10 +158,84 @@ function MyComponent() {
 
 For more see the [supported tasks](https://docs.geobase.app/geoai/supported-tasks)
 
+## Map Providers
+
+GeoAI.js supports multiple map tile providers:
+
+### TMS (Tile Map Service)
+TMS is a tile-based map specification that uses a bottom-left origin coordinate system. Perfect for custom tile servers and OpenAerialMap.
+
+```javascript
+// Option 1: Using URL template with placeholders (recommended)
+const pipeline = await geoai.pipeline([{ task: "object-detection" }], {
+  provider: "tms",
+  baseUrl: "https://tile.example.com/tiles/{z}/{x}/{y}.png",
+  apiKey: "your-api-key", // optional
+  tileSize: 256, // optional, defaults to 256
+  attribution: "Custom TMS Provider", // optional
+});
+
+// Option 2: Using base URL (legacy format, still supported)
+const pipeline = await geoai.pipeline([{ task: "object-detection" }], {
+  provider: "tms",
+  baseUrl: "https://tile.example.com/tiles",
+  extension: "png", // optional, defaults to "png"
+  apiKey: "your-api-key", // optional
+  tileSize: 256, // optional, defaults to 256
+  attribution: "Custom TMS Provider", // optional
+});
+```
+
+### ESRI
+ESRI World Imagery - no API key required.
+
+```javascript
+const pipeline = await geoai.pipeline([{ task: "object-detection" }], {
+  provider: "esri",
+});
+```
+
+### Mapbox
+Requires a Mapbox API key.
+
+```javascript
+const pipeline = await geoai.pipeline([{ task: "object-detection" }], {
+  provider: "mapbox",
+  apiKey: "your-mapbox-api-key",
+  style: "mapbox://styles/mapbox/satellite-v9",
+});
+```
+
+### Geobase
+Requires Geobase project credentials.
+
+```javascript
+const pipeline = await geoai.pipeline([{ task: "object-detection" }], {
+  provider: "geobase",
+  projectRef: "your-project-ref",
+  apikey: "your-api-key",
+  cogImagery: "https://path-to-your-cog.tif",
+});
+```
+
+## Talk
+
+**[Bringing Earth Observation AI to the Browser with WebGPU](talks/lightning-talk-webgpu-geoai.md)** — lightning talk at Big Data from Space 2025 (Decision Labs).
+
+<div align="center">
+  <a href="https://geobase-docs.s3.amazonaws.com/geobase-ai-assets/talks/lightning-talk-webgpu-geoai.pdf">
+    <img src="https://geobase-docs.s3.amazonaws.com/geobase-ai-assets/talks/geoaijs.png" alt="GeoAI.js talk preview" width="480">
+  </a>
+</div>
+
+- [Slides (PDF)](https://geobase-docs.s3.amazonaws.com/geobase-ai-assets/talks/lightning-talk-webgpu-geoai.pdf)
+- [Slide source (Marp)](talks/lightning-talk-webgpu-geoai.md)
+
 ## Links
 
 - **Documentation**: [docs.geobase.app/geoai](https://docs.geobase.app/geoai) - Comprehensive documentation, examples, and API reference
 - **Live Examples**: [docs.geobase.app/geoai-live](https://docs.geobase.app/geoai-live) - Interactive examples and demos
+- **Roadmap**: [_docs4devs/ROADMAP.md](_docs4devs/ROADMAP.md) - Planned docs, quantization pipeline, and related backlog
 - **Community**: [GitHub Discussions](https://github.com/decision-labs/geoai.js/discussions) - Ask questions, share ideas, and connect with other developers
 - **Code**: [GitHub Repository](https://github.com/decision-labs/geoai.js) - Source code and contributions
 - **Issues**: [GitHub Issues](https://github.com/decision-labs/geoai.js/issues) - Report bugs and request features

package/geoai.js

@@ -390,7 +390,7 @@ const postProcessYoloOutput = (model_outputs, pixel_values, rawImage, id2label)
   return model_output;
 };
 const parametersChanged = (instance, model_id, providerParams, modelParams) => {
-  var _a, _b, _c, _d, _e, _f, _g;
+  var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l;
   if (instance.model_id !== model_id) {
     return true;
   }
@@ -415,6 +415,16 @@ const parametersChanged = (instance, model_id, providerParams, modelParams) => {
         return true;
       }
       break;
+    case "tms":
+      if (((_h = instance.providerParams) == null ? void 0 : _h.baseUrl) !== (providerParams == null ? void 0 : providerParams.baseUrl)) {
+        return true;
+      }
+      break;
+    case "wms":
+      if (((_i = instance.providerParams) == null ? void 0 : _i.baseUrl) !== (providerParams == null ? void 0 : providerParams.baseUrl) || ((_j = instance.providerParams) == null ? void 0 : _j.layers) !== (providerParams == null ? void 0 : providerParams.layers) || ((_k = instance.providerParams) == null ? void 0 : _k.version) !== (providerParams == null ? void 0 : providerParams.version) || ((_l = instance.providerParams) == null ? void 0 : _l.crs) !== (providerParams == null ? void 0 : providerParams.crs)) {
+        return true;
+      }
+      break;
   }
   if (modelParams) {
     const instanceModelParams = instance.modelParams || {};
@@ -984,6 +994,7 @@ var ErrorType = /* @__PURE__ */ ((ErrorType2) => {
   ErrorType2["MaximumTileCountExceeded"] = "MaximumTileCountExceeded";
   ErrorType2["UnknownTask"] = "UnknownTask";
   ErrorType2["MissingInputField"] = "MissingInputField";
+  ErrorType2["ImageLoadFailed"] = "ImageLoadFailed";
   return ErrorType2;
 })(ErrorType || {});
 const ErrorCodes = {
@@ -998,7 +1009,11 @@ const ErrorCodes = {
   [
     "MissingInputField"
     /* MissingInputField */
-  ]: 1003
+  ]: 1003,
+  [
+    "ImageLoadFailed"
+    /* ImageLoadFailed */
+  ]: 1004
   // Add more error codes here as needed
 };
 class GeobaseError extends Error {
@@ -1241,6 +1256,130 @@ class Esri extends MapSource {
     return `${instance.serviceUrl}/${instance.serviceName}/MapServer/tile/${z}/${y}/${x}`;
   }
 }
+class Tms extends MapSource {
+  constructor(config) {
+    super();
+    __publicField(this, "baseUrl");
+    __publicField(this, "extension");
+    __publicField(this, "apiKey");
+    __publicField(this, "attribution");
+    __publicField(this, "tileSize");
+    __publicField(this, "headers");
+    __publicField(this, "scheme");
+    this.baseUrl = config.baseUrl;
+    this.extension = config.extension || "png";
+    this.apiKey = config.apiKey;
+    this.attribution = config.attribution || "TMS Provider";
+    this.tileSize = config.tileSize || 256;
+    this.headers = config.headers;
+    this.scheme = config.scheme || "WebMercator";
+  }
+  getTileUrlFromTileCoords(tileCoords, instance) {
+    const [x, originalY, z] = tileCoords;
+    const y = instance.scheme === "TMS" ? Math.pow(2, z) - 1 - originalY : originalY;
+    let url;
+    if (instance.baseUrl.includes("{x}") || instance.baseUrl.includes("{y}") || instance.baseUrl.includes("{z}")) {
+      url = instance.baseUrl.replaceAll("{z}", z.toString()).replaceAll("{x}", x.toString()).replaceAll("{y}", y.toString());
+    } else {
+      url = `${instance.baseUrl}/${z}/${x}/${y}.${instance.extension}`;
+    }
+    if (instance.apiKey) {
+      url += `?apikey=${instance.apiKey}`;
+    }
+    return url;
+  }
+}
+function formatWmsBbox(bbox2, crs, version) {
+  const [minX, minY, maxX, maxY] = bbox2;
+  if (version === "1.3.0" && crs === "EPSG:4326") {
+    return `${minY},${minX},${maxY},${maxX}`;
+  }
+  return `${minX},${minY},${maxX},${maxY}`;
+}
+function getTileBbox(tileCoords, crs, tileSize) {
+  const [x, y, z] = tileCoords;
+  if (crs === "EPSG:3857") {
+    const toMeters = pixelsToMeters;
+    const min = toMeters([x * tileSize, y * tileSize, z], tileSize);
+    const max = toMeters([(x + 1) * tileSize, (y + 1) * tileSize, z], tileSize);
+    return [
+      Math.min(min[0], max[0]),
+      Math.min(min[1], max[1]),
+      Math.max(min[0], max[0]),
+      Math.max(min[1], max[1])
+    ];
+  }
+  return tileToBBox(tileCoords);
+}
+function buildWmsGetMapUrl(config, tileCoords) {
+  const version = config.version ?? "1.1.1";
+  const crs = config.crs ?? "EPSG:3857";
+  const tileSize = config.tileSize ?? 256;
+  const bbox2 = getTileBbox(tileCoords, crs, tileSize);
+  const bboxParam = formatWmsBbox(bbox2, crs, version);
+  const params = {
+    SERVICE: "WMS",
+    REQUEST: "GetMap",
+    VERSION: version,
+    LAYERS: config.layers,
+    STYLES: config.styles ?? "",
+    FORMAT: config.format ?? "image/png",
+    WIDTH: tileSize.toString(),
+    HEIGHT: tileSize.toString(),
+    BBOX: bboxParam,
+    ...version === "1.3.0" ? { CRS: crs } : { SRS: crs },
+    ...config.transparent ? { TRANSPARENT: "TRUE" } : {},
+    ...config.extraParams ?? {}
+  };
+  const url = new URL(config.baseUrl);
+  for (const [key, value] of Object.entries(params)) {
+    url.searchParams.set(key, value);
+  }
+  return url.toString();
+}
+class Wms extends MapSource {
+  constructor(config) {
+    super();
+    __publicField(this, "baseUrl");
+    __publicField(this, "layers");
+    __publicField(this, "version");
+    __publicField(this, "crs");
+    __publicField(this, "format");
+    __publicField(this, "styles");
+    __publicField(this, "transparent");
+    __publicField(this, "attribution");
+    __publicField(this, "tileSize");
+    __publicField(this, "headers");
+    __publicField(this, "extraParams");
+    this.baseUrl = config.baseUrl;
+    this.layers = config.layers;
+    this.version = config.version ?? "1.1.1";
+    this.crs = config.crs ?? "EPSG:3857";
+    this.format = config.format ?? "image/png";
+    this.styles = config.styles ?? "";
+    this.transparent = config.transparent ?? false;
+    this.attribution = config.attribution ?? "WMS Provider";
+    this.tileSize = config.tileSize ?? 256;
+    this.headers = config.headers;
+    this.extraParams = config.extraParams;
+  }
+  getTileUrlFromTileCoords(tileCoords, instance) {
+    return buildWmsGetMapUrl(
+      {
+        baseUrl: instance.baseUrl,
+        layers: instance.layers,
+        version: instance.version,
+        crs: instance.crs,
+        format: instance.format,
+        styles: instance.styles,
+        transparent: instance.transparent,
+        tileSize: instance.tileSize,
+        extraParams: instance.extraParams
+      },
+      tileCoords
+    );
+  }
+}
 class BaseModel {
   constructor(model_id, providerParams, modelParams) {
     __publicField(this, "providerParams");
@@ -1284,6 +1423,32 @@ class BaseModel {
           attribution: this.providerParams.attribution
         });
         break;
+      case "tms":
+        this.dataProvider = new Tms({
+          baseUrl: this.providerParams.baseUrl,
+          extension: this.providerParams.extension,
+          apiKey: this.providerParams.apiKey,
+          attribution: this.providerParams.attribution,
+          tileSize: this.providerParams.tileSize,
+          headers: this.providerParams.headers,
+          scheme: this.providerParams.scheme
+        });
+        break;
+      case "wms":
+        this.dataProvider = new Wms({
+          baseUrl: this.providerParams.baseUrl,
+          layers: this.providerParams.layers,
+          version: this.providerParams.version,
+          crs: this.providerParams.crs,
+          format: this.providerParams.format,
+          styles: this.providerParams.styles,
+          transparent: this.providerParams.transparent,
+          attribution: this.providerParams.attribution,
+          tileSize: this.providerParams.tileSize,
+          headers: this.providerParams.headers,
+          extraParams: this.providerParams.extraParams
+        });
+        break;
       case "sentinel":
         throw new Error("Sentinel provider not implemented yet");
       default:

package/index.d.ts

@@ -132,10 +132,76 @@ declare class Esri extends MapSource {
 		number
 	], instance: Esri): string;
 }
+export interface TmsConfig {
+	baseUrl: string;
+	extension?: string;
+	apiKey?: string;
+	attribution?: string;
+	tileSize?: number;
+	headers?: Record<string, string>;
+	/**
+	 * Tile scheme to use.
+	 * - 'WebMercator': Web Mercator/XYZ (top-left origin, Y increases downward) - default for most modern services including Cesium
+	 * - 'TMS': TMS standard (bottom-left origin, Y increases upward) - traditional TMS
+	 * @default 'WebMercator'
+	 */
+	scheme?: "WebMercator" | "TMS";
+}
+declare class Tms extends MapSource {
+	baseUrl: string;
+	extension: string;
+	apiKey?: string;
+	attribution: string;
+	tileSize: number;
+	headers?: Record<string, string>;
+	scheme: "WebMercator" | "TMS";
+	constructor(config: TmsConfig);
+	protected getTileUrlFromTileCoords(tileCoords: [
+		number,
+		number,
+		number
+	], instance: Tms): string;
+}
+export type WmsVersion = "1.1.1" | "1.3.0";
+export type WmsCrs = "EPSG:3857" | "EPSG:4326";
+export interface WmsGetMapConfig {
+	baseUrl: string;
+	layers: string;
+	version?: WmsVersion;
+	crs?: WmsCrs;
+	format?: string;
+	styles?: string;
+	transparent?: boolean;
+	tileSize?: number;
+	attribution?: string;
+	headers?: Record<string, string>;
+	extraParams?: Record<string, string>;
+}
+export interface WmsConfig extends WmsGetMapConfig {
+}
+declare class Wms extends MapSource {
+	baseUrl: string;
+	layers: string;
+	version: WmsVersion;
+	crs: WmsCrs;
+	format: string;
+	styles: string;
+	transparent: boolean;
+	attribution: string;
+	tileSize: number;
+	headers?: Record<string, string>;
+	extraParams?: Record<string, string>;
+	constructor(config: WmsConfig);
+	protected getTileUrlFromTileCoords(tileCoords: [
+		number,
+		number,
+		number
+	], instance: Wms): string;
+}
 declare abstract class BaseModel {
 	protected static instance: BaseModel | null;
 	protected providerParams: ProviderParams;
-	protected dataProvider: Mapbox | Geobase | Esri | undefined;
+	protected dataProvider: Mapbox | Geobase | Esri | Tms | Wms | undefined;
 	protected model_id: string;
 	protected initialized: boolean;
 	protected modelParams?: PretrainedModelOptions;
@@ -430,6 +496,30 @@ export type EsriParams = {
 	tileSize?: number;
 	attribution?: string;
 };
+export type TmsParams = {
+	provider: "tms";
+	baseUrl: string;
+	extension?: string;
+	apiKey?: string;
+	attribution?: string;
+	tileSize?: number;
+	headers?: Record<string, string>;
+	scheme?: "WebMercator" | "TMS";
+};
+export type WmsParams = {
+	provider: "wms";
+	baseUrl: string;
+	layers: string;
+	version?: "1.1.1" | "1.3.0";
+	crs?: "EPSG:3857" | "EPSG:4326";
+	format?: string;
+	styles?: string;
+	transparent?: boolean;
+	attribution?: string;
+	tileSize?: number;
+	headers?: Record<string, string>;
+	extraParams?: Record<string, string>;
+};
 export interface InferenceInputs {
 	polygon: GeoJSON.Feature;
 	classLabel?: string;
@@ -448,7 +538,7 @@ export interface InferenceParams {
 	postProcessingParams?: PostProcessingParams;
 	mapSourceParams?: MapSourceParams;
 }
-export type ProviderParams = MapboxParams | SentinelParams | GeobaseParams | EsriParams;
+export type ProviderParams = MapboxParams | SentinelParams | GeobaseParams | EsriParams | TmsParams | WmsParams;
 export type HuggingFaceModelTask = "mask-generation" | "zero-shot-object-detection" | "zero-shot-image-classification" | "object-detection" | "oriented-object-detection" | "image-feature-extraction";
 export type GeobaseAiModelTask = "damage-assessment" | "vegetation-classification" | "land-cover-classification" | "land-use-classification" | "land-cover-change-detection" | "land-use-change-detection" | "solar-panel-detection" | "ship-detection" | "car-detection" | "wetland-segmentation" | "building-detection" | "oil-storage-tank-detection" | "building-footprint-segmentation";
 export type ModelInstance = MaskGeneration | ZeroShotObjectDetection | ObjectDetection | OrientedObjectDetection | LandCoverClassification | SolarPanelDetection | ShipDetection | CarDetection | WetLandSegmentation | BuildingDetection | OilStorageTankDetection | BuildingFootPrintSegmentation | ImageFeatureExtraction;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "geoai",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "A JavaScript library for running Geo AI models in frontend applications",
   "keywords": [
     "geoai",
@@ -57,7 +57,7 @@
     "publish:build": "cd build && npm publish --access public --ignore-scripts",
     "publish:pkg": "pnpm prepublish:prep && pnpm publish:build",
     "build:core": "tsc && vite build",
-    "build:types": "dts-bundle-generator --config ./dts-bundle-generator.config.ts",
+    "build:types": "dts-bundle-generator --config ./dts-bundle-generator.config.cjs",
     "build:package": "copyfiles ./package.json build",
     "build:examples": "pnpm build && cp -r ./build ./examples/codepen-geobase",
     "test": "vitest",