Skip to main content

Map Tile/File

When UDFs are called, they run and return the output of the execution. They can be called in two ways that influence how Fused handles them: File and Tile.

Single File​

In File mode, the UDF runs within a single HTTP response. This is suitable for tasks that can be completed in a single request, such as processing data that fits in memory.

File

Map Tiles​

Tile mode is designed to process geospatial datasets in grid-based tiles that align with web map tiling schemas. Each Tile request may correspond to a spatial slice of a larger dataset, making it ideal to work with large datasets that can be spatially filtered.

When a UDF endpoint is called as Tile, Fused passes bbox as the first argument, which the UDF can use to spatially filter the dataset. The bbox object specifies a tile by its bounds or XYZ index.

File

This is in contrast with a File call, where the UDF runs within a single HTTP response. In File mode, the UDF doesn't receive a bbox object to spatially filter data into tiles.

Responses with spatial data can render on a map. GeoDataFrames already contain spatial geometry information. If a raster does not contain spatial information, the bounds must be specified alongside the output object, separated by a comma, to determine its location on a map.

return arr, [xmin, ymin, xmax, ymax]

The bbox object​

A UDF may use the bbox parameter to spatially filter datasets and load into memory only the data that corresponds to the bbox spatial bounds. This reduces latency and data transfer costs. Cloud-optimized formats are particularly suited for these operations - they include Cloud Optimized GeoTiff, Geoparquet, and GeoArrow.

bbox object types​

The bbox object defines the spatial bounds of the Tile, which can be represented as a geometry object or XYZ index.

fused.types.Tile​

This is a geopandas.GeoDataFrame with x, y, z, and geometry columns.

@fused.udf
def udf(bbox: fused.types.Tile=None):
    print(bbox)

>>>      x    y   z                                           geometry
>>> 0  327  790  11  POLYGON ((-122.0 37.0, -122.0 37.1, -122.1 37.1, -122.1 37.0, -122.0 37.0))

fused.types.Bounds​

This is a list of 4 points representing the bounds (extent) of a geometry. The 4 points represent [xmin, ymin, xmax, ymax] of the bounds.

@fused.udf
def udf(bbox: fused.types.Bounds=None):
    print(bbox)

>>> [-1.52244399, 48.62747869, -1.50004107, 48.64359255]
note

As fused.types.Bounds is a list of 4 points it cannot be returned in a UDF directly. The simplest way to return it is to convert it to a GeoDataFrame:

@fused.udf
def udf(bbox: fused.types.Bounds=None):
    import shapely
    import geopandas as gpd

    print(bbox)

    bbox = gpd.GeoDataFrame(geometry=[shapely.box(*bbox)], crs=4326)
    return bbox

fused also comes with many handy utils functions that allow you to quickly access these common operations:

@fused.udf
def udf(bbox: fused.types.Bounds=None):
    bbox = fused.utils.common.bounds_to_gdf(bbox)
    return bbox
Comparison of TileGDF and ViewportGDF geometries in Workbench Map View

Comparing the same UDF with a different bounds input

  1. bounds: fused.types.Tile

Tile UDF

  1. bounds: fused.types.Bounds

(We also turn bounds into a gpd.GeoDataFrame to render it in Workbench)

Bounds UDF

Legacy types​

These types are still currently supported in fused though only for legacy reasons and will soon be deprecated.

[Legacy] fused.types.TileGDF​

This behaves the same as fused.types.Tile.

[Legacy] fused.types.ViewportGDF​

This is a geopandas.geodataframe.GeoDataFrame with a geometry column corresponding to the coordinates of the current viewport in the Map.

@fused.udf
def udf(bbox: fused.types.ViewportGDF=None):
    print(bbox)
    return bbox

>>>  geometry
>>>  POLYGON ((-122.0 37.0, -122.0 37.1, -122.1 37.1, -122.1 37.0, -122.0 37.0))

Call HTTP endpoints​

A UDF called via an HTTP endpoint is invoked as File or Tile, depending on the URL structure.

File endpoint​

This endpoint structure runs a UDF as a File. See implementation examples with Felt and Google Sheets for vector.

https://www.fused.io/server/.../run/file?dtype_out_vector=csv
info

In some cases, dtype_out_vector=json may return an error. This can happen when a GeoDataFrame without a geometry column is being return or a Pandas DataFrame. You can bypass this by using dtype_out_vector=geojson.

Tile endpoint​

This endpoint structure runs a UDF as a Tile. The {z}/{x}/{y} templated path parameters correspond to the Tile's XYZ index, which Tiled web map clients dynamically populate. See implementation examples for Raster Tiles with Felt and DeckGL, and for Vector Tiles with DeckGL and Mapbox.

https://www.fused.io/server/.../run/tiles/{z}/{x}/{y}?&dtype_out_vector=csv

Tile UDF behavior in fused.run()​

UDFs behave different when using fused.types.Tile than in any other case. When passing a gpd.GeoDataFrame. shapely.Geometry to bbox:

fused.run(tile_udf, bbox=bbox)

Or passing X Y Z:

fused.run(tile_udf, x=1, y=2, z=3)

The tile_udf gets tiled and run on Web mercator XYZ tiles and then combined back together to speed up processing rather than executing a single run.

This is in contrast to most other UDFs (either using no bbox input at all or using bbox: fused.types.Bounds) which run a single run across the given input.