geoai 1.0.4 → 1.0.6

package/CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.0.6] - 2026-07-16
+
+### Added
+- ChangeStar ViT-B building footprint model (`geobase/changestar-building-segmentation-vitb`)
+- Building segmentation factory to route Hub `modelId` to the correct runner
+
+### Changed
+- `building-footprint-segmentation` now defaults to ChangeStar; pass
+  `modelId: "geobase/building-footprint-segmentation"` for the lighter model
+
+## [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
+
 ## [1.0.4] - 2026-07-11
 
 ### Added

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.6/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.6/geoai.min.js"></script>
 ```
 
 When using CDN, the library is available globally as `geoai`.
@@ -235,6 +235,7 @@ const pipeline = await geoai.pipeline([{ task: "object-detection" }], {
 
 - **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
@@ -247,4 +248,4 @@ We welcome contributions! Please see our [contributing guide](CONTRIBUTING.md) f
 
 MIT License - see [LICENSE.md](LICENSE.md) for details.
 
-[//]: <> (Toggle CI on)
+[//]: <> (Toggle CI off)

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, _h;
+  var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l;
   if (instance.model_id !== model_id) {
     return true;
   }
@@ -419,6 +419,12 @@ const parametersChanged = (instance, model_id, providerParams, modelParams) => {
       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 || {};
@@ -1283,6 +1289,97 @@ class Tms extends MapSource {
     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");
@@ -1337,6 +1434,21 @@ class BaseModel {
           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:
@@ -2997,6 +3109,377 @@ const _OilStorageTankDetection = class _OilStorageTankDetection extends BaseMode
 };
 __publicField(_OilStorageTankDetection, "instance", null);
 let OilStorageTankDetection = _OilStorageTankDetection;
+class BaseDenseSegmentationModel extends BaseModel {
+  constructor(model_id, providerParams, modelParams) {
+    super(model_id, providerParams, modelParams);
+    __publicField(this, "model");
+    __publicField(this, "processor");
+    /** Tile edge length in pixels. */
+    __publicField(this, "tileSize", 1024);
+    /** Overlap between adjacent tiles for feather blending. */
+    __publicField(this, "tileOverlap", 64);
+    /** Default probability threshold for binarization. */
+    __publicField(this, "defaultThreshold", 0.5);
+  }
+  async initializeModel() {
+    if (this.model) return;
+    this.processor = await ImageProcessor.from_pretrained(this.model_id);
+    const pretrainedModel = await PreTrainedModel.from_pretrained(
+      this.model_id,
+      this.modelParams
+    );
+    this.model = pretrainedModel.sessions.model;
+  }
+  resolveProbabilityOutput(outputs) {
+    const tensor = outputs[this.outputName];
+    if (!tensor) {
+      throw new Error(
+        `Model output "${this.outputName}" not found; got [${Object.keys(outputs).join(", ")}]`
+      );
+    }
+    const dims = tensor.dims;
+    const raw = tensor.data ?? tensor.cpuData;
+    return {
+      type: tensor.type,
+      dims,
+      size: tensor.size,
+      data: raw
+    };
+  }
+  featherWeight(size, overlap) {
+    const ramp = new Float32Array(size);
+    ramp.fill(1);
+    if (overlap > 0) {
+      for (let i = 0; i < overlap; i++) {
+        const t = i / (overlap - 1 || 1);
+        ramp[i] = t;
+        ramp[size - 1 - i] = t;
+      }
+    }
+    const weights = new Float32Array(size * size);
+    for (let y = 0; y < size; y++) {
+      for (let x = 0; x < size; x++) {
+        weights[y * size + x] = ramp[y] * ramp[x];
+      }
+    }
+    return weights;
+  }
+  async runTile(tileImage) {
+    if (!this.processor || !this.model) {
+      throw new Error("Model or processor not initialized");
+    }
+    const inputs = await this.processor(tileImage);
+    const pixelValues = inputs.pixel_values;
+    const dataCopy = pixelValues.data instanceof Float32Array ? new Float32Array(pixelValues.data) : Float32Array.from(pixelValues.data);
+    const feed = new Tensor("float32", dataCopy, pixelValues.dims);
+    let outputs;
+    try {
+      outputs = await this.model.run({
+        [this.inputName]: feed
+      });
+    } catch (err) {
+      const detail = err instanceof Error ? err.message : typeof err === "number" ? `ONNX Runtime abort (${err}) — often WASM out-of-memory for this ${this.tileSize}px fp32 model. Try WebGPU (Chrome/Edge) or a smaller AOI.` : String(err);
+      throw new Error(`Dense segmentation tile inference failed: ${detail}`);
+    }
+    const { data } = this.resolveProbabilityOutput(outputs);
+    return {
+      data,
+      height: this.tileSize,
+      width: this.tileSize
+    };
+  }
+  /**
+   * Overlapped tiled inference with feather blending, matching the
+   * ChangeStar pipeline (tile_size / overlap / threshold).
+   */
+  async inferDenseMask(geoRawImage, threshold) {
+    const { height, width } = geoRawImage;
+    const tileSize = this.tileSize;
+    const overlap = Math.min(this.tileOverlap, tileSize - 1);
+    const stride = tileSize - overlap;
+    const feather = this.featherWeight(tileSize, overlap);
+    const accum = new Float32Array(height * width);
+    const weightSum = new Float32Array(height * width);
+    for (let rowOff = 0; rowOff < height; rowOff += stride) {
+      for (let colOff = 0; colOff < width; colOff += stride) {
+        const winH = Math.min(tileSize, height - rowOff);
+        const winW = Math.min(tileSize, width - colOff);
+        const croppedRaw = await geoRawImage.crop([
+          colOff,
+          rowOff,
+          colOff + winW - 1,
+          rowOff + winH - 1
+        ]);
+        const padH = tileSize - winH;
+        const padW = tileSize - winW;
+        const paddedRaw = padH > 0 || padW > 0 ? await croppedRaw.pad([0, padW, 0, padH]) : croppedRaw;
+        const tileImage = GeoRawImage.fromRawImage(
+          paddedRaw,
+          geoRawImage.getBounds(),
+          geoRawImage.getCRS()
+        );
+        const { data: prob } = await this.runTile(tileImage);
+        for (let y = 0; y < winH; y++) {
+          for (let x = 0; x < winW; x++) {
+            const srcIdx = y * tileSize + x;
+            const dstIdx = (rowOff + y) * width + (colOff + x);
+            const w = feather[y * tileSize + x];
+            accum[dstIdx] += prob[srcIdx] * w;
+            weightSum[dstIdx] += w;
+          }
+        }
+      }
+    }
+    const binary = new Uint8Array(height * width);
+    for (let i = 0; i < height * width; i++) {
+      const w = weightSum[i] === 0 ? 1 : weightSum[i];
+      binary[i] = accum[i] / w > threshold ? 255 : 0;
+    }
+    const scale = height > 512 || width > 512 ? 2 : 1;
+    const contourH = Math.max(1, Math.floor(height / scale));
+    const contourW = Math.max(1, Math.floor(width / scale));
+    let contourBinary = binary;
+    let contourImage = geoRawImage;
+    if (scale > 1) {
+      contourBinary = new Uint8Array(contourH * contourW);
+      for (let y = 0; y < contourH; y++) {
+        for (let x = 0; x < contourW; x++) {
+          contourBinary[y * contourW + x] = binary[y * scale * width + x * scale];
+        }
+      }
+      contourImage = new GeoRawImage(
+        contourBinary,
+        contourW,
+        contourH,
+        1,
+        geoRawImage.getBounds(),
+        geoRawImage.getCRS()
+      );
+    }
+    const maskTensor = new Tensor("uint8", contourBinary, [
+      1,
+      1,
+      contourH,
+      contourW
+    ]);
+    const masksToFC = maskToGeoJSON({ mask: [maskTensor] }, contourImage);
+    const features = [];
+    masksToFC.forEach((fc) => {
+      fc.features.forEach((feature2) => {
+        feature2.properties = {
+          ...feature2.properties || {},
+          class: "building"
+        };
+        features.push(feature2);
+      });
+    });
+    return {
+      type: "FeatureCollection",
+      features
+    };
+  }
+  async inference(params) {
+    const {
+      inputs: { polygon: polygon2 },
+      postProcessingParams: { confidenceThreshold } = {},
+      mapSourceParams
+    } = params;
+    if (!polygon2) {
+      throw new Error("Polygon input is required for dense segmentation");
+    }
+    if (!polygon2.geometry || polygon2.geometry.type !== "Polygon") {
+      throw new Error("Input must be a valid GeoJSON Polygon feature");
+    }
+    if (!this.initialized) {
+      await this.initialize();
+    }
+    if (!this.model || !this.processor || !this.dataProvider) {
+      throw new Error("Model or data provider not initialized");
+    }
+    const geoRawImage = await this.polygonToImage(
+      polygon2,
+      mapSourceParams == null ? void 0 : mapSourceParams.zoomLevel,
+      mapSourceParams == null ? void 0 : mapSourceParams.bands,
+      mapSourceParams == null ? void 0 : mapSourceParams.expression
+    );
+    const threshold = typeof confidenceThreshold === "number" ? confidenceThreshold : this.defaultThreshold;
+    const taskName = this.model_id.split("/").pop() ?? "dense-segmentation";
+    const inferenceStartTime = performance.now();
+    console.log(`[${taskName}] starting dense segmentation inference...`);
+    const detections = await this.inferDenseMask(geoRawImage, threshold);
+    const inferenceEndTime = performance.now();
+    console.log(
+      `[${taskName}] inference completed. Time taken: ${(inferenceEndTime - inferenceStartTime).toFixed(2)}ms`
+    );
+    return {
+      detections,
+      geoRawImage
+    };
+  }
+}
+const _ChangeStarBuildingSegmentation = class _ChangeStarBuildingSegmentation extends BaseDenseSegmentationModel {
+  constructor(model_id, providerParams, modelParams) {
+    super(model_id, providerParams, modelParams);
+    __publicField(this, "inputName", "image");
+    __publicField(this, "outputName", "building_prob");
+    __publicField(this, "tileSize", 1024);
+    __publicField(this, "tileOverlap", 64);
+    __publicField(this, "defaultThreshold", 0.5);
+  }
+  static async getInstance(model_id, providerParams, modelParams) {
+    if (!_ChangeStarBuildingSegmentation.instanceRef || parametersChanged(
+      _ChangeStarBuildingSegmentation.instanceRef,
+      model_id,
+      providerParams,
+      modelParams
+    )) {
+      _ChangeStarBuildingSegmentation.instanceRef = new _ChangeStarBuildingSegmentation(
+        model_id,
+        providerParams,
+        modelParams
+      );
+      await _ChangeStarBuildingSegmentation.instanceRef.initialize();
+    }
+    return { instance: _ChangeStarBuildingSegmentation.instanceRef };
+  }
+};
+__publicField(_ChangeStarBuildingSegmentation, "instanceRef", null);
+__publicField(_ChangeStarBuildingSegmentation, "default_huggingface_id", "geobase/changestar-building-segmentation-vitb");
+let ChangeStarBuildingSegmentation = _ChangeStarBuildingSegmentation;
+const _ImageFeatureExtraction = class _ImageFeatureExtraction extends BaseModel {
+  constructor(model_id, providerParams, modelParams) {
+    super(model_id, providerParams, modelParams);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    __publicField(this, "extractor");
+    __publicField(this, "patchSize");
+  }
+  static async getInstance(model_id, providerParams, modelParams) {
+    if (!_ImageFeatureExtraction.instance || parametersChanged(
+      _ImageFeatureExtraction.instance,
+      model_id,
+      providerParams,
+      modelParams
+    )) {
+      _ImageFeatureExtraction.instance = new _ImageFeatureExtraction(
+        model_id,
+        providerParams,
+        modelParams
+      );
+      await _ImageFeatureExtraction.instance.initialize();
+    }
+    return { instance: _ImageFeatureExtraction.instance };
+  }
+  async initializeModel() {
+    this.extractor = await pipeline(
+      "image-feature-extraction",
+      this.model_id,
+      this.modelParams
+    );
+    this.extractor.processor.image_processor.do_resize = false;
+    this.patchSize = this.extractor.model.config.patch_size;
+  }
+  /**
+   * Performs image feature extraction on a geographic area specified by a GeoJSON polygon.
+   * Extracts dense feature representations using DINOv3 and computes patch-to-patch similarities.
+   *
+   * @param params - Inference parameters containing polygon and processing options
+   * @returns Promise<ImageFeatureExtractionResults> containing feature vectors, similarity matrix, and metadata
+   * @throws {Error} If data provider, model or processor are not properly initialized
+   */
+  async inference(params) {
+    var _a, _b;
+    const {
+      inputs: { polygon: polygon2 },
+      postProcessingParams: { similarityThreshold = 0.5 } = {},
+      mapSourceParams
+    } = params;
+    if (!polygon2) {
+      throw new Error("Polygon input is required for feature extraction");
+    }
+    if (!polygon2.geometry || polygon2.geometry.type !== "Polygon") {
+      throw new Error("Input must be a valid GeoJSON Polygon feature");
+    }
+    if (!this.initialized) {
+      await this.initialize();
+    }
+    if (!this.extractor || !this.patchSize) {
+      throw new Error("Feature extractor not properly initialized");
+    }
+    const geoRawImage = await this.polygonToImage(
+      polygon2,
+      mapSourceParams == null ? void 0 : mapSourceParams.zoomLevel,
+      mapSourceParams == null ? void 0 : mapSourceParams.bands,
+      mapSourceParams == null ? void 0 : mapSourceParams.expression
+    );
+    const inferenceStartTime = performance.now();
+    console.log("[image-feature-extraction] starting inference...");
+    try {
+      const features = await this.extractor(geoRawImage, {
+        pooling: "none"
+      });
+      const numRegisterTokens = this.extractor.model.config.num_register_tokens ?? 0;
+      const startIndex = 1 + numRegisterTokens;
+      const patchFeatures = features.slice(null, [startIndex, null]);
+      const normalizedFeatures = patchFeatures.normalize(2, -1);
+      const scores = await matmul(
+        normalizedFeatures,
+        normalizedFeatures.permute(0, 2, 1)
+      );
+      const similarityMatrix = (await scores.tolist())[0];
+      const featureVectors = (await patchFeatures.tolist())[0];
+      let filteredFeatures = featureVectors;
+      let filteredSimilarityMatrix = similarityMatrix;
+      if (similarityThreshold > 0) {
+        const highSimilarityPatches = /* @__PURE__ */ new Set();
+        for (let i = 0; i < similarityMatrix.length; i++) {
+          for (let j = 0; j < similarityMatrix[i].length; j++) {
+            if (i !== j && similarityMatrix[i][j] >= similarityThreshold) {
+              highSimilarityPatches.add(i);
+              highSimilarityPatches.add(j);
+            }
+          }
+        }
+        const patchIndices = Array.from(highSimilarityPatches).sort(
+          (a, b) => a - b
+        );
+        filteredFeatures = patchIndices.map((i) => featureVectors[i]);
+        filteredSimilarityMatrix = patchIndices.map(
+          (i) => patchIndices.map((j) => similarityMatrix[i][j])
+        );
+      }
+      const inferenceEndTime = performance.now();
+      console.log(
+        `[image-feature-extraction] inference completed. Time taken: ${(inferenceEndTime - inferenceStartTime).toFixed(2)}ms`
+      );
+      const result = {
+        features: filteredFeatures,
+        similarityMatrix: filteredSimilarityMatrix,
+        patchSize: this.patchSize,
+        geoRawImage,
+        metadata: {
+          numPatches: filteredFeatures.length,
+          featureDimensions: ((_a = filteredFeatures[0]) == null ? void 0 : _a.length) || 0,
+          modelId: this.model_id
+        }
+      };
+      console.log("[image-feature-extraction] Result structure:", {
+        featuresLength: result.features.length,
+        similarityMatrixLength: result.similarityMatrix.length,
+        patchSize: result.patchSize,
+        geoRawImageBounds: (_b = result.geoRawImage) == null ? void 0 : _b.getBounds(),
+        metadata: result.metadata
+      });
+      return result;
+    } catch (error) {
+      console.error("Feature extraction error:", error);
+      throw new Error(
+        `Feature extraction failed: ${error instanceof Error ? error.message : "Unknown error"}`
+      );
+    }
+  }
+};
+__publicField(_ImageFeatureExtraction, "instance", null);
+let ImageFeatureExtraction = _ImageFeatureExtraction;
 const _BuildingFootPrintSegmentation = class _BuildingFootPrintSegmentation extends BaseModel {
   constructor(model_id, providerParams, modelParams) {
     super(model_id, providerParams, modelParams);
@@ -3166,141 +3649,42 @@ const _BuildingFootPrintSegmentation = class _BuildingFootPrintSegmentation exte
   }
 };
 __publicField(_BuildingFootPrintSegmentation, "instance", null);
+__publicField(_BuildingFootPrintSegmentation, "default_huggingface_id", "geobase/building-footprint-segmentation");
 let BuildingFootPrintSegmentation = _BuildingFootPrintSegmentation;
-const _ImageFeatureExtraction = class _ImageFeatureExtraction extends BaseModel {
-  constructor(model_id, providerParams, modelParams) {
-    super(model_id, providerParams, modelParams);
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    __publicField(this, "extractor");
-    __publicField(this, "patchSize");
-  }
-  static async getInstance(model_id, providerParams, modelParams) {
-    if (!_ImageFeatureExtraction.instance || parametersChanged(
-      _ImageFeatureExtraction.instance,
-      model_id,
-      providerParams,
-      modelParams
-    )) {
-      _ImageFeatureExtraction.instance = new _ImageFeatureExtraction(
-        model_id,
-        providerParams,
-        modelParams
+const buildingFootprintFactory = (params, modelId, modelParams) => BuildingFootPrintSegmentation.getInstance(modelId, params, modelParams);
+const changeStarFactory = (params, modelId, modelParams) => ChangeStarBuildingSegmentation.getInstance(
+  modelId,
+  params,
+  modelParams ?? { dtype: "fp32" }
+);
+const buildingSegmentationFactories = {
+  [BuildingFootPrintSegmentation.default_huggingface_id]: buildingFootprintFactory,
+  [ChangeStarBuildingSegmentation.default_huggingface_id]: changeStarFactory
+};
+const BuildingSegmentationFactory = {
+  get knownModelIds() {
+    return Object.keys(buildingSegmentationFactories);
+  },
+  getInstance(params, modelId, modelParams) {
+    const resolvedId = modelId == null ? void 0 : modelId.trim();
+    if (!resolvedId) {
+      return Promise.reject(
+        new Error(
+          `Building segmentation modelId is required. Known ids: ${this.knownModelIds.join(", ")}`
+        )
       );
-      await _ImageFeatureExtraction.instance.initialize();
     }
-    return { instance: _ImageFeatureExtraction.instance };
-  }
-  async initializeModel() {
-    this.extractor = await pipeline(
-      "image-feature-extraction",
-      this.model_id,
-      this.modelParams
-    );
-    this.extractor.processor.image_processor.do_resize = false;
-    this.patchSize = this.extractor.model.config.patch_size;
-  }
-  /**
-   * Performs image feature extraction on a geographic area specified by a GeoJSON polygon.
-   * Extracts dense feature representations using DINOv3 and computes patch-to-patch similarities.
-   *
-   * @param params - Inference parameters containing polygon and processing options
-   * @returns Promise<ImageFeatureExtractionResults> containing feature vectors, similarity matrix, and metadata
-   * @throws {Error} If data provider, model or processor are not properly initialized
-   */
-  async inference(params) {
-    var _a, _b;
-    const {
-      inputs: { polygon: polygon2 },
-      postProcessingParams: { similarityThreshold = 0.5 } = {},
-      mapSourceParams
-    } = params;
-    if (!polygon2) {
-      throw new Error("Polygon input is required for feature extraction");
-    }
-    if (!polygon2.geometry || polygon2.geometry.type !== "Polygon") {
-      throw new Error("Input must be a valid GeoJSON Polygon feature");
-    }
-    if (!this.initialized) {
-      await this.initialize();
-    }
-    if (!this.extractor || !this.patchSize) {
-      throw new Error("Feature extractor not properly initialized");
-    }
-    const geoRawImage = await this.polygonToImage(
-      polygon2,
-      mapSourceParams == null ? void 0 : mapSourceParams.zoomLevel,
-      mapSourceParams == null ? void 0 : mapSourceParams.bands,
-      mapSourceParams == null ? void 0 : mapSourceParams.expression
-    );
-    const inferenceStartTime = performance.now();
-    console.log("[image-feature-extraction] starting inference...");
-    try {
-      const features = await this.extractor(geoRawImage, {
-        pooling: "none"
-      });
-      const numRegisterTokens = this.extractor.model.config.num_register_tokens ?? 0;
-      const startIndex = 1 + numRegisterTokens;
-      const patchFeatures = features.slice(null, [startIndex, null]);
-      const normalizedFeatures = patchFeatures.normalize(2, -1);
-      const scores = await matmul(
-        normalizedFeatures,
-        normalizedFeatures.permute(0, 2, 1)
-      );
-      const similarityMatrix = (await scores.tolist())[0];
-      const featureVectors = (await patchFeatures.tolist())[0];
-      let filteredFeatures = featureVectors;
-      let filteredSimilarityMatrix = similarityMatrix;
-      if (similarityThreshold > 0) {
-        const highSimilarityPatches = /* @__PURE__ */ new Set();
-        for (let i = 0; i < similarityMatrix.length; i++) {
-          for (let j = 0; j < similarityMatrix[i].length; j++) {
-            if (i !== j && similarityMatrix[i][j] >= similarityThreshold) {
-              highSimilarityPatches.add(i);
-              highSimilarityPatches.add(j);
-            }
-          }
-        }
-        const patchIndices = Array.from(highSimilarityPatches).sort(
-          (a, b) => a - b
-        );
-        filteredFeatures = patchIndices.map((i) => featureVectors[i]);
-        filteredSimilarityMatrix = patchIndices.map(
-          (i) => patchIndices.map((j) => similarityMatrix[i][j])
-        );
-      }
-      const inferenceEndTime = performance.now();
-      console.log(
-        `[image-feature-extraction] inference completed. Time taken: ${(inferenceEndTime - inferenceStartTime).toFixed(2)}ms`
-      );
-      const result = {
-        features: filteredFeatures,
-        similarityMatrix: filteredSimilarityMatrix,
-        patchSize: this.patchSize,
-        geoRawImage,
-        metadata: {
-          numPatches: filteredFeatures.length,
-          featureDimensions: ((_a = filteredFeatures[0]) == null ? void 0 : _a.length) || 0,
-          modelId: this.model_id
-        }
-      };
-      console.log("[image-feature-extraction] Result structure:", {
-        featuresLength: result.features.length,
-        similarityMatrixLength: result.similarityMatrix.length,
-        patchSize: result.patchSize,
-        geoRawImageBounds: (_b = result.geoRawImage) == null ? void 0 : _b.getBounds(),
-        metadata: result.metadata
-      });
-      return result;
-    } catch (error) {
-      console.error("Feature extraction error:", error);
-      throw new Error(
-        `Feature extraction failed: ${error instanceof Error ? error.message : "Unknown error"}`
+    const create = buildingSegmentationFactories[resolvedId];
+    if (!create) {
+      return Promise.reject(
+        new Error(
+          `Unknown building segmentation modelId "${resolvedId}". Known ids: ${this.knownModelIds.join(", ")}`
+        )
       );
     }
+    return create(params, resolvedId, modelParams);
   }
 };
-__publicField(_ImageFeatureExtraction, "instance", null);
-let ImageFeatureExtraction = _ImageFeatureExtraction;
 const modelRegistry = [
   {
     task: "zero-shot-object-detection",
@@ -3485,20 +3869,14 @@ const modelRegistry = [
   {
     task: "building-footprint-segmentation",
     library: "geoai",
-    description: "Segments the precise outlines (footprints) of buildings in imagery. Useful for mapping, urban planning, or disaster assessment.",
+    description: "Segments the precise outlines (footprints) of buildings in imagery. Defaults to ChangeStar ViT-B; pass modelId for the lighter footprint model. Useful for mapping, urban planning, or disaster assessment.",
     examples: [
       "Segment building footprints in this city block.",
       "Identify the outlines of all buildings in this image.",
       "Find building perimeters in this urban area."
     ],
     ioConfig: {},
-    geobase_ai_pipeline: (params, modelId = "geobase/building-footprint-segmentation", modelParams) => {
-      return BuildingFootPrintSegmentation.getInstance(
-        modelId,
-        params,
-        modelParams
-      );
-    }
+    geobase_ai_pipeline: (params, modelId = ChangeStarBuildingSegmentation.default_huggingface_id, modelParams) => BuildingSegmentationFactory.getInstance(params, modelId, modelParams)
   },
   {
     task: "image-feature-extraction",

package/index.d.ts

@@ -162,10 +162,46 @@ declare class Tms extends MapSource {
 		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 | Tms | undefined;
+	protected dataProvider: Mapbox | Geobase | Esri | Tms | Wms | undefined;
 	protected model_id: string;
 	protected initialized: boolean;
 	protected modelParams?: PretrainedModelOptions;
@@ -411,6 +447,7 @@ declare class BuildingFootPrintSegmentation extends BaseModel {
 	protected static instance: BuildingFootPrintSegmentation | null;
 	protected model: ort.InferenceSession | undefined;
 	protected processor: ImageProcessor | undefined;
+	static readonly default_huggingface_id = "geobase/building-footprint-segmentation";
 	private constructor();
 	static getInstance(model_id: string, providerParams: ProviderParams, modelParams?: PretrainedModelOptions): Promise<{
 		instance: BuildingFootPrintSegmentation;
@@ -438,6 +475,53 @@ declare class ImageFeatureExtraction extends BaseModel {
 	 */
 	inference(params: InferenceParams): Promise<ImageFeatureExtractionResults>;
 }
+declare abstract class BaseDenseSegmentationModel extends BaseModel {
+	protected model: ort.InferenceSession | undefined;
+	protected processor: ImageProcessor | undefined;
+	/** ONNX input feed name (e.g. "image"). */
+	protected abstract readonly inputName: string;
+	/** Soft-probability output tensor name (e.g. "building_prob"). */
+	protected abstract readonly outputName: string;
+	/** Tile edge length in pixels. */
+	protected readonly tileSize: number;
+	/** Overlap between adjacent tiles for feather blending. */
+	protected readonly tileOverlap: number;
+	/** Default probability threshold for binarization. */
+	protected readonly defaultThreshold: number;
+	protected constructor(model_id: string, providerParams: ProviderParams, modelParams?: PretrainedModelOptions);
+	protected initializeModel(): Promise<void>;
+	protected resolveProbabilityOutput(outputs: Record<string, any>): {
+		type: string;
+		dims: number[];
+		size: number;
+		data: Float32Array;
+	};
+	protected featherWeight(size: number, overlap: number): Float32Array;
+	protected runTile(tileImage: GeoRawImage): Promise<{
+		data: Float32Array;
+		height: number;
+		width: number;
+	}>;
+	/**
+	 * Overlapped tiled inference with feather blending, matching the
+	 * ChangeStar pipeline (tile_size / overlap / threshold).
+	 */
+	protected inferDenseMask(geoRawImage: GeoRawImage, threshold: number): Promise<GeoJSON.FeatureCollection>;
+	inference(params: InferenceParams): Promise<ObjectDetectionResults>;
+}
+declare class ChangeStarBuildingSegmentation extends BaseDenseSegmentationModel {
+	protected static instanceRef: ChangeStarBuildingSegmentation | null;
+	static readonly default_huggingface_id = "geobase/changestar-building-segmentation-vitb";
+	protected readonly inputName = "image";
+	protected readonly outputName = "building_prob";
+	protected readonly tileSize = 1024;
+	protected readonly tileOverlap = 64;
+	protected readonly defaultThreshold = 0.5;
+	private constructor();
+	static getInstance(model_id: string, providerParams: ProviderParams, modelParams?: PretrainedModelOptions): Promise<{
+		instance: ChangeStarBuildingSegmentation;
+	}>;
+}
 export type MapboxParams = {
 	provider: "mapbox";
 	apiKey: string;
@@ -470,6 +554,20 @@ export type TmsParams = {
 	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;
@@ -488,10 +586,10 @@ export interface InferenceParams {
 	postProcessingParams?: PostProcessingParams;
 	mapSourceParams?: MapSourceParams;
 }
-export type ProviderParams = MapboxParams | SentinelParams | GeobaseParams | EsriParams | TmsParams;
+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;
+export type ModelInstance = MaskGeneration | ZeroShotObjectDetection | ObjectDetection | OrientedObjectDetection | LandCoverClassification | SolarPanelDetection | ShipDetection | CarDetection | WetLandSegmentation | BuildingDetection | ChangeStarBuildingSegmentation | OilStorageTankDetection | BuildingFootPrintSegmentation | ImageFeatureExtraction;
 export type ModelConfig = {
 	task: HuggingFaceModelTask | GeobaseAiModelTask;
 	library: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "geoai",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "A JavaScript library for running Geo AI models in frontend applications",
   "keywords": [
     "geoai",