geoai 1.0.1 → 1.0.2

package/index.d.ts

@@ -0,0 +1,546 @@
+// Generated by dts-bundle-generator v9.5.1
+
+import { ImageProcessor, PretrainedModelOptions, RawImage } from '@huggingface/transformers';
+import * as ort from 'onnxruntime-web';
+
+export interface Bounds {
+	north: number;
+	south: number;
+	east: number;
+	west: number;
+}
+declare class GeoRawImage extends RawImage {
+	private bounds;
+	private transform;
+	private crs;
+	constructor(data: Uint8ClampedArray | Uint8Array, width: number, height: number, channels: 1 | 2 | 3 | 4, bounds: Bounds, crs?: string);
+	/**
+	 * Convert the image into patches.
+	 */
+	toPatches(patch_height: number, patch_width: number, { padding }?: {
+		padding?: boolean | undefined;
+	}): Promise<GeoRawImage[][]>;
+	/**
+	 * Static function to join a 2D array of RawImage patches into a single GeoRawImage.
+	 * This function assumes the patches are contiguous and form a complete grid.
+	 * @param patches A 2D array of RawImage objects to be joined.
+	 * @param bounds The bounds of the final, merged image.
+	 * @param crs The Coordinate Reference System of the final, merged image.
+	 * @returns A promise that resolves to a single GeoRawImage containing the joined data.
+	 */
+	static fromPatches(patches: RawImage[][], bounds: Bounds, crs: string): GeoRawImage;
+	/**
+	 * Convert pixel coordinates to world coordinates
+	 */
+	pixelToWorld(x: number, y: number): [
+		number,
+		number
+	];
+	/**
+	 * Convert world coordinates to pixel coordinates
+	 */
+	worldToPixel(lon: number, lat: number): [
+		number,
+		number
+	];
+	/**
+	 * Get the bounds of the image
+	 */
+	getBounds(): Bounds;
+	/**
+	 * Get the CRS of the image
+	 */
+	getCRS(): string;
+	/**
+	 * Create a new GeoRawImage from a RawImage and georeferencing information
+	 */
+	static fromRawImage(rawImage: RawImage, bounds: Bounds, crs?: string): GeoRawImage;
+	/**
+	 * Override the clone method to include georeferencing information
+	 */
+	clone(): GeoRawImage;
+}
+export type ObjectDectection = {
+	label: string;
+	score: number;
+	box: [
+		number,
+		number,
+		number,
+		number
+	];
+};
+declare const postProcessYoloOutput: (model_outputs: any, pixel_values: {
+	dims: number[];
+}, rawImage: RawImage, id2label: {
+	[key: number]: string;
+}) => ObjectDectection[];
+declare const parametersChanged: (instance: any, model_id: string, providerParams: any, modelParams?: PretrainedModelOptions) => boolean;
+declare const detectionsToGeoJSON: (detections: ObjectDectection[], geoRawImage: GeoRawImage) => GeoJSON.FeatureCollection;
+declare const maskToGeoJSON: (masks: any, geoRawImage: GeoRawImage, thresholds?: number[]) => GeoJSON.FeatureCollection[];
+declare const polygonsEqual: (polygon1: GeoJSON.Feature | null, polygon2: GeoJSON.Feature | null) => boolean;
+declare abstract class MapSource {
+	protected abstract getTileUrlFromTileCoords(tileCoords: [
+		number,
+		number,
+		number
+	], instance: any, bands?: number[], expression?: string): string;
+	getImage(polygon: any, bands?: number[], expression?: string, zoomLevel?: number, requiresSquare?: boolean, // default is false,
+	stitch?: boolean): Promise<GeoRawImage | GeoRawImage[][]>;
+}
+declare class Mapbox extends MapSource {
+	apiKey: string;
+	style: string;
+	constructor(apiKey: string, style: string);
+	protected getTileUrlFromTileCoords(tileCoords: [
+		number,
+		number,
+		number
+	], instance: Mapbox): string;
+}
+export interface GeobaseConfig {
+	projectRef: string;
+	cogImagery: string;
+	apikey: string;
+}
+declare class Geobase extends MapSource {
+	projectRef: string;
+	cogImagery: string;
+	apikey: string;
+	constructor(config: GeobaseConfig);
+	protected getTileUrlFromTileCoords(tileCoords: [
+		number,
+		number,
+		number
+	], instance: Geobase, bands?: number[], expression?: string): string;
+}
+export interface EsriConfig {
+	serviceUrl?: string;
+	serviceName?: string;
+	tileSize?: number;
+	attribution?: string;
+}
+declare class Esri extends MapSource {
+	serviceUrl: string;
+	serviceName: string;
+	tileSize: number;
+	attribution: string;
+	constructor(config: EsriConfig);
+	protected getTileUrlFromTileCoords(tileCoords: [
+		number,
+		number,
+		number
+	], instance: Esri): string;
+}
+declare abstract class BaseModel {
+	protected static instance: BaseModel | null;
+	protected providerParams: ProviderParams;
+	protected dataProvider: Mapbox | Geobase | Esri | undefined;
+	protected model_id: string;
+	protected initialized: boolean;
+	protected modelParams?: PretrainedModelOptions;
+	protected constructor(model_id: string, providerParams: ProviderParams, modelParams?: PretrainedModelOptions);
+	protected initialize(): Promise<void>;
+	protected initializeDataProvider(): void;
+	/**
+	 * Converts a GeoJSON polygon feature into a GeoRawImage using the configured data provider.
+	 *
+	 * @param polygon - The GeoJSON Feature representing the area of interest.
+	 * @param zoomLevel - (Optional) The zoom level to use when retrieving the image.
+	 * @param bands - (Optional) An array of band indices to select specific bands from the imagery.
+	 * @param expression - (Optional) A string expression to apply to the image bands (e.g., for band math).
+	 * @param requiresSquare - (default false) Whether to return a square image.
+	 * @returns A Promise that resolves to a GeoRawImage corresponding to the input polygon.
+	 * @throws {Error} If the data provider is not initialized.
+	 */
+	protected polygonToImage(polygon: GeoJSON.Feature, zoomLevel?: number, bands?: number[], expression?: string, requiresSquare?: boolean, stitch?: boolean): Promise<GeoRawImage | GeoRawImage[][]>;
+	protected abstract initializeModel(): Promise<void>;
+	abstract inference(params: InferenceParams): Promise<unknown>;
+}
+export interface SegmentationResult {
+	masks: GeoJSON.FeatureCollection;
+	geoRawImage: GeoRawImage;
+}
+declare class MaskGeneration extends BaseModel {
+	protected static instance: MaskGeneration | null;
+	private model;
+	private processor;
+	private cachedPolygon;
+	private cachedEmbeddings;
+	private cachedGeoRawImage;
+	private constructor();
+	static getInstance(model_id: string, providerParams: ProviderParams, modelParams?: PretrainedModelOptions): Promise<{
+		instance: MaskGeneration;
+	}>;
+	protected initializeModel(): Promise<void>;
+	/**
+	 * Gets or computes image embeddings for the given polygon
+	 * Uses cached embeddings if polygon hasn't changed
+	 */
+	private getOrComputeEmbeddings;
+	/**
+	 * Performs segmentation on a geographic area based on the provided input parameters.
+	 *
+	 * @param params - Inference parameters containing:
+	 *                - inputs: Object containing polygon and segmentation input
+	 *                - postProcessingParams: Optional parameters for post-processing
+	 *                - mapSourceParams: Optional parameters for map source configuration
+	 *
+	 * @returns Promise<SegmentationResult> containing:
+	 *          - masks: GeoJSON representation of the segmentation masks
+	 *          - geoRawImage: Raw image data with geographic reference
+	 *
+	 * @throws {Error} If data provider is not initialized
+	 * @throws {Error} If model or processor is not initialized
+	 * @throws {Error} If segmentation process fails
+	 * @throws {Error} If input type is not supported
+	 */
+	inference(params: InferenceParams): Promise<SegmentationResult>;
+	getImageEmbeddings(params: InferenceParams): Promise<{
+		image_embeddings: any;
+		geoRawImage: GeoRawImage;
+	}>;
+}
+declare abstract class BaseDetectionModel extends BaseModel {
+	protected model: ort.InferenceSession | undefined;
+	protected zoom?: number;
+	protected processor: ImageProcessor | undefined;
+	protected constructor(model_id: string, providerParams: ProviderParams, modelParams?: PretrainedModelOptions);
+	protected initializeModel(): Promise<void>;
+	protected postProcessor(outputs: any, geoRawImage: GeoRawImage): Promise<GeoJSON.FeatureCollection>;
+	inference(params: InferenceParams): Promise<ObjectDetectionResults>;
+}
+declare class SolarPanelDetection extends BaseDetectionModel {
+	private static instanceRef;
+	private constructor();
+	static getInstance(model_id: string, providerParams: ProviderParams, modelParams?: PretrainedModelOptions): Promise<{
+		instance: SolarPanelDetection;
+	}>;
+}
+declare class ShipDetection extends BaseDetectionModel {
+	private static instanceRef;
+	private constructor();
+	static getInstance(model_id: string, providerParams: ProviderParams, modelParams?: PretrainedModelOptions): Promise<{
+		instance: ShipDetection;
+	}>;
+}
+declare class CarDetection extends BaseDetectionModel {
+	private static instanceRef;
+	private constructor();
+	static getInstance(model_id: string, providerParams: ProviderParams, modelParams?: PretrainedModelOptions): Promise<{
+		instance: CarDetection;
+	}>;
+}
+declare class BuildingDetection extends BaseDetectionModel {
+	private static instanceRef;
+	private constructor();
+	static getInstance(model_id: string, providerParams: ProviderParams, modelParams?: PretrainedModelOptions): Promise<{
+		instance: BuildingDetection;
+	}>;
+}
+declare class WetLandSegmentation extends BaseModel {
+	protected static instance: WetLandSegmentation | null;
+	protected model: ort.InferenceSession | undefined;
+	protected processor: ImageProcessor | undefined;
+	private constructor();
+	static getInstance(model_id: string, providerParams: ProviderParams, modelParams?: PretrainedModelOptions): Promise<{
+		instance: WetLandSegmentation;
+	}>;
+	protected initializeModel(): Promise<void>;
+	inference(params: InferenceParams): Promise<ObjectDetectionResults>;
+	protected postProcessor(outputs: any, geoRawImage: GeoRawImage): Promise<GeoJSON.FeatureCollection>;
+}
+declare class LandCoverClassification extends BaseModel {
+	protected static instance: LandCoverClassification | null;
+	private model;
+	private classes;
+	private colors;
+	private processor;
+	private constructor();
+	static getInstance(model_id: string, providerParams: ProviderParams, modelParams?: PretrainedModelOptions): Promise<{
+		instance: LandCoverClassification;
+	}>;
+	protected initializeModel(): Promise<void>;
+	inference(params: InferenceParams): Promise<any>;
+}
+declare class ObjectDetection extends BaseModel {
+	protected static instance: ObjectDetection | null;
+	private model;
+	private processor;
+	private constructor();
+	static getInstance(model_id: string, providerParams: ProviderParams, modelParams?: PretrainedModelOptions): Promise<{
+		instance: ObjectDetection;
+	}>;
+	protected initializeModel(): Promise<void>;
+	/**
+	 * Performs object detection on a geographic area specified by a GeoJSON polygon.
+	 *
+	 * @param polygon - A GeoJSON Feature representing the geographic area to analyze
+	 * @param confidence - Detection confidence threshold between 0 and 1. Detections below this threshold will be filtered out. Defaults to 0.9
+	 * @returns Promise<ObjectDetectionResults> containing detected objects as GeoJSON features and the raw image used for detection
+	 * @throws {Error} If data provider, model or processor are not properly initialized
+	 */
+	inference(params: InferenceParams): Promise<ObjectDetectionResults>;
+}
+declare class OilStorageTankDetection extends BaseModel {
+	protected static instance: OilStorageTankDetection | null;
+	protected model: ort.InferenceSession | undefined;
+	protected processor: ImageProcessor | undefined;
+	private constructor();
+	static getInstance(model_id: string, providerParams: ProviderParams, modelParams?: PretrainedModelOptions): Promise<{
+		instance: OilStorageTankDetection;
+	}>;
+	protected initializeModel(): Promise<void>;
+	inference(params: InferenceParams): Promise<ObjectDetectionResults>;
+	protected postProcessor(outputs: any, geoRawImage: GeoRawImage, CONFIDENCE_THRESHOLD?: number, NMS_THRESHOLD?: number): Promise<GeoJSON.FeatureCollection>;
+}
+export interface ConvertPredParams {
+	pred_bbox: number[][];
+	org_img_shape: [
+		number,
+		number
+	];
+	valid_scale: [
+		number,
+		number
+	];
+	conf_thresh: number;
+}
+export interface NMSOptions {
+	conf_thres?: number;
+	iou_thres?: number;
+	merge?: boolean;
+	classes?: number[];
+	multi_label?: boolean;
+	agnostic?: boolean;
+	without_iouthres?: boolean;
+}
+declare class OrientedObjectDetection extends BaseModel {
+	protected static instance: OrientedObjectDetection | null;
+	protected model: ort.InferenceSession | undefined;
+	protected initialized: boolean;
+	protected processor: ImageProcessor | undefined;
+	protected classes: string[] | undefined;
+	protected constructor(model_id: string, providerParams: ProviderParams, modelParams?: PretrainedModelOptions);
+	static getInstance(model_id: string, providerParams: ProviderParams, modelParams?: PretrainedModelOptions): Promise<{
+		instance: OrientedObjectDetection;
+	}>;
+	protected initializeModel(): Promise<void>;
+	/**
+	 * Performs object detection on a given geographic polygon.
+	 * @param polygon - A GeoJSON Feature representing the area for detection
+	 * @param options - Optional NMS (Non-Maximum Suppression) configuration options
+	 * @param {NMSOptions} [options={}] - Configuration options for NMS post-processing
+	 * @returns {Promise<ObjectDetectionResults>} A promise that resolves to the detection results, including the detections array and raw image
+	 * @throws {Error} If the data provider or model is not properly initialized
+	 */
+	inference(params: InferenceParams): Promise<ObjectDetectionResults>;
+	protected convertPred({ pred_bbox, org_img_shape, valid_scale, conf_thresh, }: ConvertPredParams): number[][];
+	/**
+	 * Performs Rotate-Non-Maximum Suppression (RNMS) on inference results.
+	 * @param prediction Array of predictions with shape (batch_size, num_boxes, [xywh, score, num_classes, num_angles]).
+	 * @param conf_thres Confidence threshold.
+	 * @param iou_thres IoU threshold.
+	 * @param classes Array of class indices to filter by.
+	 * @param without_iouthres Whether to skip IoU thresholding.
+	 * @returns Array of filtered boxes after NMS.
+	 */
+	protected nonMaxSuppression4Points(prediction: number[][][], { conf_thres, iou_thres, classes, multi_label, without_iouthres, }?: NMSOptions): number[][][];
+	/**
+	 * Polygonal NMS implementation.
+	 * @param dets Array of polygons with shape (num_detections, [poly]).
+	 * @param scores Array of confidence scores with shape (num_detections, 1).
+	 * @param thresh IoU threshold.
+	 * @returns Array of indices to keep after NMS.
+	 */
+	protected pyCpuNmsPolyFast(dets: number[][], scores: number[], thresh: number): number[];
+	protected postProcessor(outputs: any, geoRawImage: GeoRawImage, options?: NMSOptions): Promise<any>;
+}
+declare class ZeroShotObjectDetection extends BaseModel {
+	protected static instance: ZeroShotObjectDetection | null;
+	private detector;
+	rawDetections: any[];
+	protected constructor(model_id: string, providerParams: ProviderParams, modelParams?: PretrainedModelOptions);
+	static getInstance(model_id: string, providerParams: ProviderParams, modelParams?: PretrainedModelOptions): Promise<{
+		instance: ZeroShotObjectDetection;
+	}>;
+	protected initializeModel(): Promise<void>;
+	/**
+	 * Performs object detection on a geographic area using a zero-shot learning model
+	 * @param polygon - A GeoJSON Feature representing the geographic area to analyze
+	 * @param text - Label or array of labels to detect in the image
+	 * @param options - Detection configuration options
+	 * @param options.topk - Maximum number of detections to return (default: 4)
+	 * @param options.threshold - Confidence threshold for detections (default: 0.2)
+	 * @returns Promise resolving to object detection results containing GeoJSON features and raw image data
+	 * @throws Error if data provider is not initialized
+	 */
+	inference(params: InferenceParams): Promise<ObjectDetectionResults>;
+}
+declare class BuildingFootPrintSegmentation extends BaseModel {
+	protected static instance: BuildingFootPrintSegmentation | null;
+	protected model: ort.InferenceSession | undefined;
+	protected processor: ImageProcessor | undefined;
+	private constructor();
+	static getInstance(model_id: string, providerParams: ProviderParams, modelParams?: PretrainedModelOptions): Promise<{
+		instance: BuildingFootPrintSegmentation;
+	}>;
+	protected initializeModel(): Promise<void>;
+	inference(params: InferenceParams): Promise<ObjectDetectionResults>;
+	protected postProcessor(output: GeoRawImage, CONFIDENCE_THRESHOLD?: number, minArea?: number): Promise<GeoJSON.FeatureCollection>;
+}
+declare class ImageFeatureExtraction extends BaseModel {
+	protected static instance: ImageFeatureExtraction | null;
+	private extractor;
+	private patchSize;
+	private constructor();
+	static getInstance(model_id: string, providerParams: ProviderParams, modelParams?: PretrainedModelOptions): Promise<{
+		instance: ImageFeatureExtraction;
+	}>;
+	protected initializeModel(): Promise<void>;
+	/**
+	 * 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
+	 */
+	inference(params: InferenceParams): Promise<ImageFeatureExtractionResults>;
+}
+export type MapboxParams = {
+	provider: "mapbox";
+	apiKey: string;
+	style: string;
+};
+export type SentinelParams = {
+	provider: "sentinel";
+	apiKey: string;
+};
+export type GeobaseParams = {
+	provider: "geobase";
+	apikey: string;
+	cogImagery: string;
+	projectRef: string;
+};
+export type EsriParams = {
+	provider: "esri";
+	serviceUrl?: string;
+	serviceName?: string;
+	tileSize?: number;
+	attribution?: string;
+};
+export interface InferenceInputs {
+	polygon: GeoJSON.Feature;
+	classLabel?: string;
+	[key: string]: unknown;
+}
+export type PostProcessingParams = {
+	[key: string]: unknown;
+};
+export interface MapSourceParams {
+	zoomLevel?: number;
+	bands?: number[];
+	expression?: string;
+}
+export interface InferenceParams {
+	inputs: InferenceInputs;
+	postProcessingParams?: PostProcessingParams;
+	mapSourceParams?: MapSourceParams;
+}
+export type ProviderParams = MapboxParams | SentinelParams | GeobaseParams | EsriParams;
+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 ModelConfig = {
+	task: HuggingFaceModelTask | GeobaseAiModelTask;
+	library: string;
+	description: string;
+	examples?: string[];
+	geobase_ai_pipeline: (params: ProviderParams, modelId?: string, modelParams?: PretrainedModelOptions) => Promise<{
+		instance: ModelInstance;
+	}>;
+	chainableTasks?: string[];
+	ioConfig?: {
+		inputs: any;
+		outputs: any;
+	};
+	defaultModelId?: string;
+	modelParams?: PretrainedModelOptions;
+};
+export interface SegmentationResults {
+	detections: GeoJSON.FeatureCollection;
+	masks: GeoJSON.FeatureCollection;
+	geoRawImage: GeoRawImage;
+	rawDetections: any[];
+}
+export interface ObjectDetectionResults {
+	detections: GeoJSON.FeatureCollection;
+	geoRawImage: GeoRawImage;
+}
+export interface ImageFeatureExtractionResults {
+	features: number[][];
+	similarityMatrix: number[][];
+	patchSize: number;
+	geoRawImage: GeoRawImage;
+	metadata: {
+		numPatches: number;
+		featureDimensions: number;
+		modelId: string;
+	};
+}
+export interface ChainInstance {
+	inference: (inputs: InferenceParams) => Promise<ObjectDetectionResults | SegmentationResults>;
+}
+export interface TaskConfig {
+	task: string;
+	modelId?: string;
+	modelParams?: PretrainedModelOptions;
+}
+declare class Pipeline {
+	/**
+	 * Builds a dependency graph from modelRegistry chainableTasks
+	 */
+	private static buildTaskGraph;
+	/**
+	 * Finds all valid task chains using BFS
+	 */
+	static findValidChains(tasks: string[]): string[][];
+	/**
+	 * Orders tasks in a valid chainable sequence
+	 */
+	private static orderChainTasks;
+	/**
+	 * Validates and reorders tasks array in-place
+	 */
+	private static validateChainCompatibility;
+	/**
+	 * Validates input for a specific task
+	 */
+	private static validateTaskInput;
+	/**
+	 * Creates a pipeline for a single task or a chain of tasks
+	 * @param taskOrTasks Single task or list of tasks to chain
+	 * @param providerParams Provider parameters
+	 * @returns A function that takes inputs and returns the output of the last task in the chain
+	 */
+	static pipeline(taskOrTasks: TaskConfig[], providerParams: ProviderParams): Promise<ModelInstance | ChainInstance>;
+	static listTasks(): string[];
+	static listModels(): ModelConfig[];
+}
+export declare const geoai: {
+	pipeline: typeof Pipeline.pipeline;
+	tasks: typeof Pipeline.listTasks;
+	models: typeof Pipeline.listModels;
+	validateChain: typeof Pipeline.findValidChains;
+};
+
+declare namespace utils {
+	export { detectionsToGeoJSON, maskToGeoJSON, parametersChanged, polygonsEqual, postProcessYoloOutput };
+}
+
+export {
+	utils,
+};
+
+export {};

package/package.json

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