Custom and hosted imagery
Beyond Siter's built-in basemaps (Open Streetmap, Azure, Google), projects can use custom imagery sources you configure (XYZ, WMS, ArcGIS REST, GeoTIFF URLs) and hosted imagery that customers upload to the Siter server. Hosted imagery is scoped per customer and can be shared across that customer's projects.
Added in v0.22.
Prerequisites
- Custom imagery — you must have the Project Administration Permission on the project, plus the URL or address of the source you want to use
- Hosted imagery use — once uploaded, any project assigned the imagery can use it as a basemap
Custom imagery
Custom imagery lets you point a project at any compatible tile or imagery service.
Supported source types
| Source | Use case |
|---|---|
| XYZ | Standard z/x/y tile services (e.g., Stamen, custom Mapbox styles, internal tile servers) |
| WMS | OGC Web Map Service — a layer from an OGC server |
| ArcGIS REST | Map services and image services hosted on ArcGIS Server or ArcGIS Online |
| GeoTIFF (URL) | A GeoTIFF accessible at a public URL — Siter streams it as imagery |
How to add a custom imagery source
Custom imagery is configured directly from the Map Background dropdown on the Feature Layers sidebar:
- In the Feature Layers sidebar, open the Map Background dropdown
- Select the custom-source entry for the type you need (XYZ, WMS, ArcGIS REST, or GeoTIFF)
- In the field that appears, enter the source URL (and any auth tokens or layer names required)
- Click Save
The source is then active as the map background and remains selectable in the Map Background dropdown.
Custom-source entries appear in the Map Background dropdown only for users with the Project Administration Permission. The dropdown shown to other users lists only the built-in and already-configured sources.
Hosted imagery
Hosted imagery is a GeoTIFF you upload directly to the Siter server. Siter converts it to a Cloud-Optimized GeoTIFF (COG) in the background if GDAL is available, then serves it as imagery without depending on an external URL.
How to upload hosted imagery
- Open the customer admin page (administrators) or your customer's imagery management area
- Click Upload Imagery
- Select a GeoTIFF file
- The upload returns immediately; the row transitions Pending → Converting → Active as the server processes it
- Once Active, the imagery can be assigned to projects
If the Siter server has GDAL configured, non-COG uploads are auto-converted to COG. If GDAL is not available, the server runs in strict-mode and rejects non-COG uploads with a clear message at upload time. Check GET /api/system/info for the server's capability status.
How to assign hosted imagery to a project
- In the Feature Layers sidebar, open the Map Background dropdown and select the Hosted Imagery entry
- A Hosted Imagery picker appears, listing the GeoTIFFs uploaded to your customer. Each row shows its processing status (Pending, Converting, or Active) and flags any file missing on disk
- Choose an Active imagery to use it as the background
Use the menu (⋮) next to the Hosted Imagery picker to Upload a new GeoTIFF. The first hosted imagery selected on a project with no other basemap is auto-selected.
How to share hosted imagery across customers
Administrators can share hosted imagery from one customer with another customer by assigning it to a project that belongs to the receiving customer. The imagery itself stays scoped to the originating customer; assignment just makes it visible.
How to delete hosted imagery
- Open the imagery management area
- Click the delete icon on the imagery row
- Confirm the typed-confirm guard
Deletion is transactional — the database row and underlying file are removed together. Once deleted, projects that referenced the imagery fall back to their next configured basemap.
Deleting hosted imagery affects every project assigned to it. Verify which projects rely on the imagery before deleting.
Troubleshooting
Uploaded imagery is slow to load
Cause: The GeoTIFF is large or not yet converted to COG.
Solution: Wait for the Active status. If it stays in Converting for a long time, check the customer's GDAL configuration with an administrator. Large files (multi-GB) take noticeably longer to render even after conversion — consider clipping the source to the project area before upload.
Custom imagery does not appear in the Map Background dropdown
Cause: The source URL is unreachable from the user's browser, or auth credentials are missing.
Solution: Verify the URL loads in a new browser tab. For ArcGIS REST and WMS sources behind auth, confirm the credentials in the custom source configuration. Network-restricted sources may need a tile proxy.