geobase/changestar-building-segmentation-vitb

Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

Hugging Face Inference Endpoint

The root handler.py is a thin adapter around the versioned ChangeStarHandler integration. Hugging Face still discovers the model-local EndpointHandler, while shared downloading, validation, tiling, inference, response, and bucket logic is maintained in one package. It loads onnx/model_quantized.onnx when available and falls back to onnx/model.onnx.

Send the complete handler request inside inputs:

{
  "inputs": {
    "imagery": "https://huggingface.co/datasets/geobase/geoai-cogs/resolve/main/geoembeddings-demo/building-detection_sm.tif"
  }
}

Place optional fields such as output_crs, threshold, and use_bucket alongside imagery inside inputs. tile_size must remain 1024: the exported ViT has fixed positional embeddings even though its ONNX input metadata uses symbolic height and width. With no bucket configuration, the endpoint returns the detected polygons inline. GeoJSON uses EPSG:4326 by default.

imagery also accepts typed GeoTIFF, ESRI ImageServer, and Mapbox raster inputs documented in the shared imagery guide. Set MAPBOX_ACCESS_TOKEN for Mapbox requests and ESRI_TOKEN only for secured ESRI services.

ESRI ImageServer example

This example requests NAIP imagery over the same WGS84 bounds from the public USGS ImageServer:

{
  "inputs": {
    "imagery": {
      "type": "esri",
      "url": "https://imagery.nationalmap.gov/arcgis/rest/services/USGSNAIPImagery/ImageServer",
      "polygon": {
        "type": "Polygon",
        "coordinates": [[
          [-117.59587065763711, 47.651865889977294],
          [-117.58845496125399, 47.651865889977294],
          [-117.58845496125399, 47.65414974834855],
          [-117.59587065763711, 47.65414974834855],
          [-117.59587065763711, 47.651865889977294]
        ]]
      },
      "mapParams": {
        "size": [1024, 1024],
        "interpolation": "RSP_BilinearInterpolation",
        "bandIds": [0, 1, 2]
      }
    }
  }
}

This public service does not require ESRI_TOKEN. Configure that endpoint secret only when using a secured ImageServer.

Mapbox example

Configure MAPBOX_ACCESS_TOKEN as an Inference Endpoint secret, then send:

{
  "inputs": {
    "imagery": {
      "type": "mapbox",
      "polygon": {
        "type": "Polygon",
        "coordinates": [[
          [-117.59587065763711, 47.651865889977294],
          [-117.58845496125399, 47.651865889977294],
          [-117.58845496125399, 47.65414974834855],
          [-117.59587065763711, 47.65414974834855],
          [-117.59587065763711, 47.651865889977294]
        ]]
      },
      "mapParams": {
        "tileset": "mapbox.satellite",
        "zoom": 17,
        "tileSize": 256,
        "imageFormat": "png"
      }
    }
  }
}

{
  "polygon_count": 12,
  "building_pixels": 3456,
  "building_coverage": 0.013,
  "width": 1024,
  "height": 1024,
  "crs": "EPSG:4326",
  "output_crs": "EPSG:4326",
  "geojson": {
    "type": "FeatureCollection",
    "features": []
  },
  "duration_seconds": 2.4
}

Optional Hub bucket output

Bucket storage is optional. If it is configured, the handler uploads buildings.geojson and buildings_mask.tif and returns their bucket keys instead of embedding the GeoJSON in the HTTP response.

Environment variable	Required	Description
HF_BUCKET	For uploads	Full bucket id, such as geobase/building-results
HF_TOKEN or HUGGING_FACE_HUB_TOKEN	For uploads	Token with write access to the bucket namespace
HF_OUTPUT_PREFIX	No	Object prefix; defaults to building-segmentation/

When both the bucket and token are present, uploads are enabled automatically. Set "use_bucket": false inside inputs to force an inline response. Set "use_bucket": true to require an upload; the request fails clearly if the endpoint is not configured with both variables. An optional output_prefix can override the generated per-request key prefix.

Configure HF_BUCKET and HF_TOKEN as secrets/environment variables on the Inference Endpoint, then send:

{
  "inputs": {
    "imagery": "https://example.com/image.tif",
    "use_bucket": true
  }
}

The token is never included in the request body. output_prefix is optional; without it, the handler generates a unique dated path.

Example bucket response:

{
  "polygon_count": 12,
  "storage": {
    "provider": "huggingface_hub",
    "bucket": "geobase/building-results",
    "keys": [
      "building-segmentation/20260718/abc/buildings.geojson",
      "building-segmentation/20260718/abc/buildings_mask.tif"
    ]
  }
}