geoai 1.0.5 → 1.0.7

package/CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.0.7] - 2026-07-17
+
+### Added
+- OpenAerialMap (OAM) map provider — HOT Imagery STAC + TiTiler (`provider: "oam"`)
+- `examples/07-oam-quickstart` — Rome orthophoto draw-to-detect demo
+- OAM option in `live-examples-nextjs` (flies to Rome; mosaic tiles)
+
+### Fixed
+- Docs Vercel prebuild: ship `remark` deps with docs and run `generate-llms-txt` from `docs/scripts/` so module resolution works when the Vercel root is `docs/`
+
+## [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
@@ -16,9 +36,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - 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
-- `live-examples-nextjs` pins `geoai` to local `build/` for WMS/TMS provider development
-
 ## [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.5/geoai.js"></script>
+<script src="https://unpkg.com/geoai@1.0.7/geoai.js"></script>
 ```
 
 #### jsDelivr CDN
 ```html
-<script src="https://cdn.jsdelivr.net/npm/geoai@1.0.5/geoai.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/geoai@1.0.7/geoai.min.js"></script>
 ```
 
 When using CDN, the library is available globally as `geoai`.
@@ -186,6 +186,17 @@ const pipeline = await geoai.pipeline([{ task: "object-detection" }], {
 });
 ```
 
+### OpenAerialMap (OAM)
+Community aerial imagery via HOT Imagery STAC + TiTiler — no API key.
+
+```javascript
+const pipeline = await geoai.pipeline([{ task: "object-detection" }], {
+  provider: "oam",
+  // itemId: "67826781a07cc20001818cdb", // optional pin
+  // mosaic: true, // optional: collection mosaic only
+});
+```
+
 ### ESRI
 ESRI World Imagery - no API key required.
 
@@ -231,6 +242,39 @@ const pipeline = await geoai.pipeline([{ task: "object-detection" }], {
 - [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)
 
+## Agents & LLMs
+
+### Install the GeoAI agent skill
+
+Use the [Skills CLI](https://skills.sh/) so coding agents (Cursor, Claude Code, Codex, etc.) load GeoAI.js integration guidance automatically:
+
+```bash
+# Install into the current project (recommended)
+npx skills add decision-labs/geoai.js --skill geoai -y
+
+# Or install globally for all projects
+npx skills add decision-labs/geoai.js --skill geoai -g -y
+```
+
+List what you have installed:
+
+```bash
+npx skills list
+```
+
+Use the skill once without installing (pipes a prompt into an agent):
+
+```bash
+npx skills use decision-labs/geoai.js@geoai
+```
+
+Source: [`skills/geoai`](skills/geoai) — pipeline API, task picker, providers, and Web Worker patterns for background inference.
+
+### LLM-readable docs
+
+- **Index**: [docs.geobase.app/geoai/llms.txt](https://docs.geobase.app/geoai/llms.txt)
+- **Full corpus**: [docs.geobase.app/geoai/llms-full.txt](https://docs.geobase.app/geoai/llms-full.txt) — regenerate with `pnpm docs:llms`
+
 ## Links
 
 - **Documentation**: [docs.geobase.app/geoai](https://docs.geobase.app/geoai) - Comprehensive documentation, examples, and API reference
@@ -248,4 +292,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, _i, _j, _k, _l;
+  var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l, _m, _n, _o, _p, _q, _r;
   if (instance.model_id !== model_id) {
     return true;
   }
@@ -425,6 +425,11 @@ const parametersChanged = (instance, model_id, providerParams, modelParams) => {
         return true;
       }
       break;
+    case "oam":
+      if (((_m = instance.providerParams) == null ? void 0 : _m.stacUrl) !== (providerParams == null ? void 0 : providerParams.stacUrl) || ((_n = instance.providerParams) == null ? void 0 : _n.rasterUrl) !== (providerParams == null ? void 0 : providerParams.rasterUrl) || ((_o = instance.providerParams) == null ? void 0 : _o.collection) !== (providerParams == null ? void 0 : providerParams.collection) || ((_p = instance.providerParams) == null ? void 0 : _p.asset) !== (providerParams == null ? void 0 : providerParams.asset) || ((_q = instance.providerParams) == null ? void 0 : _q.itemId) !== (providerParams == null ? void 0 : providerParams.itemId) || ((_r = instance.providerParams) == null ? void 0 : _r.mosaic) !== (providerParams == null ? void 0 : providerParams.mosaic)) {
+        return true;
+      }
+      break;
   }
   if (modelParams) {
     const instanceModelParams = instance.modelParams || {};
@@ -1380,6 +1385,175 @@ class Wms extends MapSource {
     );
   }
 }
+const DEFAULT_OAM_STAC_URL = "https://api.imagery.hotosm.org/stac";
+const DEFAULT_OAM_RASTER_URL = "https://api.imagery.hotosm.org/raster";
+const DEFAULT_OAM_COLLECTION = "openaerialmap";
+const DEFAULT_OAM_ASSET = "visual";
+function buildOamMosaicTileUrlTemplate(rasterUrl = DEFAULT_OAM_RASTER_URL, collection = DEFAULT_OAM_COLLECTION, asset = DEFAULT_OAM_ASSET) {
+  const base = rasterUrl.replace(/\/$/, "");
+  return `${base}/collections/${encodeURIComponent(collection)}/tiles/WebMercatorQuad/{z}/{x}/{y}?assets=${encodeURIComponent(asset)}`;
+}
+function buildOamItemTileUrlTemplate(itemId, rasterUrl = DEFAULT_OAM_RASTER_URL, collection = DEFAULT_OAM_COLLECTION, asset = DEFAULT_OAM_ASSET) {
+  const base = rasterUrl.replace(/\/$/, "");
+  return `${base}/collections/${encodeURIComponent(collection)}/items/${encodeURIComponent(itemId)}/tiles/WebMercatorQuad/{z}/{x}/{y}@1x?assets=${encodeURIComponent(asset)}`;
+}
+function pickBestOamItem(features) {
+  if (!features.length) return void 0;
+  return features.slice().sort((a, b) => {
+    var _a, _b, _c, _d, _e, _f;
+    const gsdA = typeof ((_a = a.properties) == null ? void 0 : _a.gsd) === "number" ? a.properties.gsd : Number.POSITIVE_INFINITY;
+    const gsdB = typeof ((_b = b.properties) == null ? void 0 : _b.gsd) === "number" ? b.properties.gsd : Number.POSITIVE_INFINITY;
+    if (gsdA !== gsdB) return gsdA - gsdB;
+    const dateA = Date.parse(
+      String(((_c = a.properties) == null ? void 0 : _c.created) || ((_d = a.properties) == null ? void 0 : _d.datetime) || 0)
+    );
+    const dateB = Date.parse(
+      String(((_e = b.properties) == null ? void 0 : _e.created) || ((_f = b.properties) == null ? void 0 : _f.datetime) || 0)
+    );
+    return dateB - dateA;
+  })[0];
+}
+async function searchOamItems(bbox2, options = {}) {
+  const stacUrl = (options.stacUrl || DEFAULT_OAM_STAC_URL).replace(/\/$/, "");
+  const collection = options.collection || DEFAULT_OAM_COLLECTION;
+  const limit = options.limit ?? 10;
+  const fetchImpl = options.fetchImpl || fetch;
+  const response = await fetchImpl(`${stacUrl}/search`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Accept: "application/geo+json",
+      ...options.headers || {}
+    },
+    body: JSON.stringify({
+      collections: [collection],
+      bbox: bbox2,
+      limit
+    })
+  });
+  if (!response.ok) {
+    const body = await response.text().catch(() => "");
+    throw new Error(
+      `OAM STAC search failed (${response.status}): ${body || response.statusText}`
+    );
+  }
+  const data = await response.json();
+  return data.features || [];
+}
+class Oam extends MapSource {
+  constructor(config = {}) {
+    super();
+    __publicField(this, "stacUrl");
+    __publicField(this, "rasterUrl");
+    __publicField(this, "collection");
+    __publicField(this, "asset");
+    __publicField(this, "itemId");
+    __publicField(this, "mosaic");
+    __publicField(this, "attribution");
+    __publicField(this, "tileSize");
+    __publicField(this, "headers");
+    /** Resolved XYZ template with `{z}/{x}/{y}` placeholders. */
+    __publicField(this, "tileUrlTemplate");
+    __publicField(this, "resolvedForBboxKey");
+    this.stacUrl = (config.stacUrl || DEFAULT_OAM_STAC_URL).replace(/\/$/, "");
+    this.rasterUrl = (config.rasterUrl || DEFAULT_OAM_RASTER_URL).replace(
+      /\/$/,
+      ""
+    );
+    this.collection = config.collection || DEFAULT_OAM_COLLECTION;
+    this.asset = config.asset || DEFAULT_OAM_ASSET;
+    this.itemId = config.itemId;
+    this.mosaic = config.mosaic === true;
+    this.attribution = config.attribution || "OpenAerialMap / HOT Imagery";
+    this.tileSize = config.tileSize || 256;
+    this.headers = config.headers;
+    if (this.itemId) {
+      this.tileUrlTemplate = buildOamItemTileUrlTemplate(
+        this.itemId,
+        this.rasterUrl,
+        this.collection,
+        this.asset
+      );
+    } else if (this.mosaic) {
+      this.tileUrlTemplate = buildOamMosaicTileUrlTemplate(
+        this.rasterUrl,
+        this.collection,
+        this.asset
+      );
+    } else {
+      this.tileUrlTemplate = buildOamMosaicTileUrlTemplate(
+        this.rasterUrl,
+        this.collection,
+        this.asset
+      );
+    }
+  }
+  /**
+   * Resolve tile URL template for an AOI via STAC (unless mosaic/itemId pin).
+   */
+  async resolveTileTemplate(polygon2) {
+    if (this.itemId) {
+      this.tileUrlTemplate = buildOamItemTileUrlTemplate(
+        this.itemId,
+        this.rasterUrl,
+        this.collection,
+        this.asset
+      );
+      return this.tileUrlTemplate;
+    }
+    if (this.mosaic) {
+      this.tileUrlTemplate = buildOamMosaicTileUrlTemplate(
+        this.rasterUrl,
+        this.collection,
+        this.asset
+      );
+      return this.tileUrlTemplate;
+    }
+    const bbox$1 = bbox(polygon2);
+    const bboxKey = bbox$1.map((n) => n.toFixed(6)).join(",");
+    if (this.resolvedForBboxKey === bboxKey && this.tileUrlTemplate) {
+      return this.tileUrlTemplate;
+    }
+    const features = await searchOamItems(bbox$1, {
+      stacUrl: this.stacUrl,
+      collection: this.collection,
+      headers: this.headers
+    });
+    const best = pickBestOamItem(features);
+    if (best == null ? void 0 : best.id) {
+      this.itemId = best.id;
+      this.tileUrlTemplate = buildOamItemTileUrlTemplate(
+        best.id,
+        this.rasterUrl,
+        this.collection,
+        this.asset
+      );
+    } else {
+      this.tileUrlTemplate = buildOamMosaicTileUrlTemplate(
+        this.rasterUrl,
+        this.collection,
+        this.asset
+      );
+    }
+    this.resolvedForBboxKey = bboxKey;
+    return this.tileUrlTemplate;
+  }
+  async getImage(polygon2, bands, expression, zoomLevel, requiresSquare = false, stitch = true) {
+    await this.resolveTileTemplate(polygon2);
+    return super.getImage(
+      polygon2,
+      bands,
+      expression,
+      zoomLevel,
+      requiresSquare,
+      stitch
+    );
+  }
+  getTileUrlFromTileCoords(tileCoords, instance) {
+    const [x, y, z] = tileCoords;
+    return instance.tileUrlTemplate.replaceAll("{z}", z.toString()).replaceAll("{x}", x.toString()).replaceAll("{y}", y.toString());
+  }
+}
 class BaseModel {
   constructor(model_id, providerParams, modelParams) {
     __publicField(this, "providerParams");
@@ -1449,6 +1623,19 @@ class BaseModel {
           extraParams: this.providerParams.extraParams
         });
         break;
+      case "oam":
+        this.dataProvider = new Oam({
+          stacUrl: this.providerParams.stacUrl,
+          rasterUrl: this.providerParams.rasterUrl,
+          collection: this.providerParams.collection,
+          asset: this.providerParams.asset,
+          itemId: this.providerParams.itemId,
+          mosaic: this.providerParams.mosaic,
+          attribution: this.providerParams.attribution,
+          tileSize: this.providerParams.tileSize,
+          headers: this.providerParams.headers
+        });
+        break;
       case "sentinel":
         throw new Error("Sentinel provider not implemented yet");
       default:
@@ -3109,6 +3296,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);
@@ -3278,141 +3836,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",
@@ -3597,20 +4056,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

@@ -198,10 +198,59 @@ declare class Wms extends MapSource {
 		number
 	], instance: Wms): string;
 }
+export interface OamConfig {
+	/** STAC API root (default HOT Imagery STAC). */
+	stacUrl?: string;
+	/** TiTiler / raster API root. */
+	rasterUrl?: string;
+	/** STAC collection id. */
+	collection?: string;
+	/** Asset key used for RGB tiles (default `visual`). */
+	asset?: string;
+	/**
+	 * Pin to a specific STAC item id. Skips search.
+	 * Item tiles: `/collections/{collection}/items/{itemId}/tiles/...`
+	 */
+	itemId?: string;
+	/**
+	 * When true, use the collection mosaic tile endpoint (no STAC search).
+	 * When false (default) and `itemId` is unset, search STAC for the AOI and
+	 * use the best matching item's tiles (fallback to mosaic if none found).
+	 */
+	mosaic?: boolean;
+	attribution?: string;
+	tileSize?: number;
+	headers?: Record<string, string>;
+}
+declare class Oam extends MapSource {
+	stacUrl: string;
+	rasterUrl: string;
+	collection: string;
+	asset: string;
+	itemId?: string;
+	mosaic: boolean;
+	attribution: string;
+	tileSize: number;
+	headers?: Record<string, string>;
+	/** Resolved XYZ template with `{z}/{x}/{y}` placeholders. */
+	tileUrlTemplate: string;
+	private resolvedForBboxKey?;
+	constructor(config?: OamConfig);
+	/**
+	 * Resolve tile URL template for an AOI via STAC (unless mosaic/itemId pin).
+	 */
+	resolveTileTemplate(polygon: GeoJSON.Feature): Promise<string>;
+	getImage(polygon: any, bands?: number[], expression?: string, zoomLevel?: number, requiresSquare?: boolean, stitch?: boolean): Promise<GeoRawImage | GeoRawImage[][]>;
+	protected getTileUrlFromTileCoords(tileCoords: [
+		number,
+		number,
+		number
+	], instance: Oam): string;
+}
 declare abstract class BaseModel {
 	protected static instance: BaseModel | null;
 	protected providerParams: ProviderParams;
-	protected dataProvider: Mapbox | Geobase | Esri | Tms | Wms | undefined;
+	protected dataProvider: Mapbox | Geobase | Esri | Tms | Wms | Oam | undefined;
 	protected model_id: string;
 	protected initialized: boolean;
 	protected modelParams?: PretrainedModelOptions;
@@ -447,6 +496,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;
@@ -474,6 +524,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;
@@ -520,6 +617,24 @@ export type WmsParams = {
 	headers?: Record<string, string>;
 	extraParams?: Record<string, string>;
 };
+export type OamParams = {
+	provider: "oam";
+	/** STAC API root (default https://api.imagery.hotosm.org/stac). */
+	stacUrl?: string;
+	/** Raster/TiTiler API root (default https://api.imagery.hotosm.org/raster). */
+	rasterUrl?: string;
+	/** STAC collection id (default openaerialmap). */
+	collection?: string;
+	/** Asset key for RGB tiles (default visual). */
+	asset?: string;
+	/** Pin to a specific STAC item id (skips search). */
+	itemId?: string;
+	/** Use collection mosaic tiles instead of per-item STAC search. */
+	mosaic?: boolean;
+	attribution?: string;
+	tileSize?: number;
+	headers?: Record<string, string>;
+};
 export interface InferenceInputs {
 	polygon: GeoJSON.Feature;
 	classLabel?: string;
@@ -538,10 +653,10 @@ export interface InferenceParams {
 	postProcessingParams?: PostProcessingParams;
 	mapSourceParams?: MapSourceParams;
 }
-export type ProviderParams = MapboxParams | SentinelParams | GeobaseParams | EsriParams | TmsParams | WmsParams;
+export type ProviderParams = MapboxParams | SentinelParams | GeobaseParams | EsriParams | TmsParams | WmsParams | OamParams;
 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.5",
+  "version": "1.0.7",
   "description": "A JavaScript library for running Geo AI models in frontend applications",
   "keywords": [
     "geoai",
@@ -63,6 +63,7 @@
     "test": "vitest",
     "test:coverage": "vitest --coverage",
     "test:build": "pnpm run build && vitest run test/build.test.ts",
+    "docs:llms": "node ./docs/scripts/generate-llms-txt.mjs",
     "lint:scripts": "eslint . --ext .ts",
     "lint:styles": "stylelint ./**/*.{css,scss}",
     "format:scripts": "prettier . --write",