Understanding and Optimizing Cesium ion SaaS Quotas
This page will help you learn about Cesium ion SaaS usage quotas and provide tips and tricks for squeezing more value out of your account without having to upgrade plans.
Cesium ion quotas are split across four different metrics:
| Metric | Description |
|---|---|
| Bing Maps sessions | The total number of Bing Maps-based asset endpoint requests made by your account. |
| Storage | The total number of bytes of source data stored in your account. |
| Data Streaming | The total number of bytes of ion assets streamed to clients by your account (excluding Bing Maps data). |
| Geocodes | The total number of geocodes requested by your account. |
This guide will explain how each of these metrics works in practice and how you can optimize your own usage.
You can view your current usage at any time on the Usage Dashboard.
In order to provide world-class imagery out-of-the-box, CesiumJS ships with Bing Maps as the default imagery base layer. Because Bing Maps is provided by a third-party service, its usage is tracked differently than the rest of ion’s assets and has its own quota.
Bing Maps is session-based. The exact definition of an ion Bing Maps session is a successful GET request to https://api.cesium.com/v1/assets/<assetId>/endpoint, where <assetId> is the ID of a Bing-based asset. The result of this request cannot be cached across multiple pages or refreshes and can change at any time.
In CesiumJS, this means you use a session whenever you
- create the default
CesiumWidgetorViewer, - make a call to
createWorldImagery, - instantiate an instance of
IonImageryProviderwith a Bing-based asset, or - select a Bing layer in the default
BaseLayerPickerconfiguration.
Since sessions cannot be cached across pages, refreshing the page of an app using Bing Maps will use another session.
There are several ways to reduce the number of Bing Maps sessions you use.
Update CesiumJS
CesiumJS 1.58 or newer has improved caching support, which uses at most 1 Bing Maps session per map style during the lifetime of the page. Depending on your use case, you may be able to dramatically reduce Bing Maps sessions by upgrading to the latest version.
Opt out of Bing during development (or altogether)
Cesium ion provides 10-meter global resolution Sentinel-2 imagery with a generous data-based quota that makes aggressive use of browser caching. For example, with Sentinel-2, refreshing a page without changing the view will barely use additional data streaming. If you do not need Bing-quality imagery, Sentinel-2 is an excellent alternative.
Even if you would prefer to use Bing Maps in production, you can still greatly decrease the overall number of sessions by falling back to Sentinel-2 for non-production usage.
To try Sentinel-2, add the asset to your account from the asset depot and use the below snippet when creating a Cesium Viewer instance.
var viewer = new Cesium.Viewer('cesiumContainer',{
imageryProvider: new Cesium.IonImageryProvider({ assetId: 3954 })
});
Don’t use Bing Maps in automated tests
Repeatedly running integration or unit tests will create unnecessary Bing Maps sessions. For this reason, we encourage users to avoid using Bing Maps sessions in automated testing. You can either create the Cesium instance with no imagery at all, or use Sentinel-2 as defined above.
To initialize Cesium without the default Bing layer, use the following snippet:
var viewer = new Cesium.Viewer('cesiumContainer',{
imageryProvider: false,
baseLayerPicker: false
});
Disable or customize the BaseLayerPicker widget
The Cesium BaseLayerPicker widget includes several Bing assets by default. This is great for demos but you should customize what is available in your production applications to limit access to the specific layers you choose to expose. Here’s an example that uses Sentinel-2 and Blue Marble imagery from ion:
var imageryViewModels = [];
imageryViewModels.push(new Cesium.ProviderViewModel({
name: 'Sentinel-2',
iconUrl: Cesium.buildModuleUrl('Widgets/Images/ImageryProviders/sentinel-2.png'),
tooltip: 'Sentinel-2 cloudless.',
creationFunction: function () {
return new Cesium.IonImageryProvider({ assetId: 3954 });
}
}));
imageryViewModels.push(new Cesium.ProviderViewModel({
name: 'Blue Marble',
iconUrl: Cesium.buildModuleUrl('Widgets/Images/ImageryProviders/blueMarble.png'),
tooltip: 'Blue Marble Next Generation July, 2004 imagery from NASA.',
creationFunction: function () {
return new Cesium.IonImageryProvider({ assetId: 3845 });
}
}));
var viewer = new Cesium.Viewer('cesiumContainer', {
imageryProviderViewModels: imageryViewModels
});
If your application uses a single base layer that you would prefer users not be allowed to change themselves, you can disable the BaseLayerPicker altogether:
var viewer = new Cesium.Viewer('cesiumContainer',{
baseLayerPicker: false
});
Common mistakes
Using a Bing Maps session and immediately throwing it out
When you instantiate the Viewer widget, it immediately requests the Bing base layer. Calling viewer.imageryLayers.removeAll() will prevent the layer from being displayed but will still counts as a Bing Maps session.
Incorrect code
var viewer = new Cesium.Viewer('cesiumContainer');
viewer.imageryLayers.removeAll();
var viewer = new Cesium.Viewer('cesiumContainer',{
imageryProvider: false,
baseLayerPicker: false
});
var viewer = new Cesium.Viewer('cesiumContainer');
viewer.imageryLayers.addImageryProvider(new Cesium.IonImageryProvider({ assetId: 3954 }));
While this hides the base layer completely with Sentinel-2, the net effect is that both layers are requested. In addition to using a session, this also doubles the number of tiles being used by your application because Cesium still requests the hidden layer. Instead, you need to specifically tell the Viewer not to bother creating imagery at all.
Correct code
var viewer = new Cesium.Viewer('cesiumContainer',{
imageryProvider: false,
baseLayerPicker: false
});
viewer.imageryLayers.addImageryProvider(new Cesium.IonImageryProvider({ assetId: 3954 }));
Cesium ion’s storage quota is the total number of source data bytes you have uploaded into your account. This number is easily found at the top of the Assets Dashboard.
The amount of storage you are currently using is available on the assets dashboard.
This number includes only the data you upload. Tilesets and other data created by ion do not count against your storage quota. By uploading more compact formats, you can dramatically increase the amount of data you can store in ion.
Here are several tips to make the most out of your storage.
Upload zip files
Cesium ion supports uploading one or more zip files at a time. The size of many formats, like OBJ, CityGML, and DAE, can be substantially decreased by uploading a zip file instead of the individual model files. Not only will this use less space in your account, but your upload will go substantially faster as well. As an extreme example, a 50GB CityGML file may compress to as little as 3GB!
Note: The Cesium ion dashboard does not currently support zip files larger than 4GB or that contain more than 65,535 files. You can split them into separate zip files under these limits and upload them together.
Use built-in compression mechanisms
While zip files provide a huge win for most source data formats, others formats have built-in compression.
GeoTIFF
Using compressed GeoTIFFs not only reduces storage and speeds up upload time, but can also speed up the tiling process because of lower I/O overhead. If you are familiar with the GDAL command line, you can turn an uncompressed GeoTIFF into a compressed one with the following command:
gdal_translate in.tif out.tif -co COMPRESS=DEFLATE
laszip -i lidar.las -o lidar.laz
You can also further reduce the size of your LAS/LAZ files by removing unneeded Point Data Records; refer to LAStools for more information.
Texture compression
3D models often contain textures in formats that favor quality over size, such as PNG. If you do not need transparency, you can substantially decrease the size of a model by using JPG instead. This can routinely provide significant savings for texture-heavy models. Check your modeling software for options related to texture export.
Prefer glTF over OBJ and COLLADA
glTF is a modern model format built for the web. It is much more compact than equivalent OBJ or COLLADA models with no difference in quality. Because of glTF’s emphasis on interoperability, there’s a good chance that your tools can already export glTF models. See our blog post regarding glTF uploads for more information.
Prefer KMZ to KML
While it’s technically just a zip file with a different extension, KMZ files are supported by ion and provide the same benefits as zip files.
Tile your data directly from Amazon S3
If you use Amazon S3 as a cloud storage solution for your geospatial data, you can tile data directly from your S3 bucket by clicking on the Add from S3 button in the upload page.
That way you can skip the upload step and only store the tiled data in your ion account, which is significantly smaller than the source data in most cases. For example, a 100 GB zipped point cloud dataset may only be 40 GB when tiled as 3D Tiles.
Cesium ion offers 50,000 geocodes per month at all account levels and does not differentiate between an autocomplete request and a geocode request. Unlike other ion services, there is no REST API for geocoding, and it is only available through the CesiumJS Geocoder widget.
To reduce or eliminate geocode usage, disable autocomplete or the Geocoder.
Disable autocomplete
Disabling autocomplete will prevent the Geocoder widget from generating suggestions as the user types, but it will dramatically decrease the number of requests:
var viewer = new Cesium.Viewer('cesiumContainer');
viewer.geocoder.viewModel.autoComplete = false;
var viewer = new Cesium.Viewer('cesiumContainer', {
geocoder: false
});
Cesium ion aggressively caches tiles in the browser, and very little data is sent from the server if the same tiles are loaded multiple times on the same machine, even across multiple applications. However, popular applications with many users may still reach streaming quotas.
Enable WebP when tiling
The easiest way to reduce streaming usage is to reduce the amount of data that needs to be sent to the client. For texture-heavy tilesets, such as photogrammetry, ion can make use of WebP images, which are 25-34% smaller than JPEG images of equivalent quality. Switching to WebP means re-tiling your existing assets. See our WebP blog post for additional information.
Make sure caching is enabled
This is not common, but if you are using Cesium ion without a client that implements caching headers, such as a browser’s private mode or a custom desktop application, you will see elevated data streaming usage.
Increase maximum screen space error in CesiumJS
CesiumJS can request fewer tiles for a particular view if you adjust the screen space error (SSE). A higher SSE value means the camera needs to get closer to an object before more detailed tiles are loaded. The default value is 16, but you can experiment with larger values such as 24 or 32. The sweet spot will depend on your specific tileset and use case.
var tileset = new Cesium.Cesium3DTileset({
url: Cesium.IonResource.fromAssetId(5741),
maximumScreenSpaceError: 24
});
See Cesium3DTiles.maximumScreenSpaceError for additional information.
Decrease rendering resolution in CesiumJS
Similar to setting SSE, you can decrease the overall rendering resolution of CesiumJS via the Viewer.resolutionScale property. This approach reduces streaming usage by reducing the number of tiles requested from the server. To render at 75% of the default resolution, set the scale to 0.75:
var viewer = new Cesium.Viewer('cesiumContainer');
viewer.resolutionScale = 0.75;
We love when apps become successful enough that going over quota becomes an issue: it means you’re getting a lot of value out of ion. Once over quota, your account will continue to work without interruption. We will never suspend your account without making every effort to contact you over email first. Specifically:
- We’ll remind you to review the tips on this page to ensure you’re following best practices.
- We’ll ask about your specific use case to determine if there are unique tips we can provide for your application or if there are any improvements that we can make to ion to better support you.
- We can help you better understand your usage and, if needed, help you find a new plan that’s right for you.
Please don’t hesitate to contact us any time with any questions or feedback.