Registration is now open for the 2025 Cesium Developer Conference! Save your spot.

Cesium for Omniverse v0.25.0

Cesium for Unity Samples v1.16.1

CesiumJS 1.130

Technical

Cesium ion SaaS and Cesium ion Self-Hosted utilize containers to provide Cesium ion. Containers are cloud-native, lightweight, and stand-alone software packages that include everything needed to run a piece of software: the code, runtime, system tools, libraries, and settings. This encapsulation ensures that the software runs consistently across various computing environments, from development to testing and production, regardless of the underlying infrastructure. At the heart of any container is the base image, and Cesium has recently updated base images to use the Red Hat Enterprise Linux Universal Base Image as deployed by Iron Bank. Because containers are smaller than virtual machines, it reduces the surface area to patch and update as part of the software stack. 

Containers are smaller than virtual machines, reducing the surface area to patch and update as part of the software stack.

Iron Bank was created and is maintained by the US Department of Defense (DoD)’s Platform One group. The goal of Iron Bank is to provide trusted and vetted container images that can speed up deployment of commercial and open source software across the DoD. This is possible because there is an open process by which images are created and because the images are continuously monitored and continually updated for Common Vulnerabilities and Exposures (CVEs) as part of the process that builds these images. Trust is an important part of what we do at Cesium, so it’s important that we are able to trust the source of our base container images and that our users are able to trust that we work to ensure a secure product for them. 

CVEs don’t exist only in the base image itself, although that is where most of them are found. To ensure we stay on top of security reports and prevent releasing vulnerabilities to our users, Cesium also scans for CVEs. CVEs are tracked through various internet databases, with contributions by companies, security researchers, and developers. CVEs generally are reported against software as they are discovered and can appear at any layer in your container—the operating system, your build tools, or your software dependencies. At Cesium, we use open source tools like Grype to identify CVEs and then mitigate them by constantly updating our dependencies or removing unnecessary pieces of software from our containers. We run these tools in our continuous integration/continuous deployment (CI/CD) pipelines, so that no release happens without security checks. 

Creating a trusted software supply chain 

Another important consideration that has received more attention lately is the software supply chain. People consuming software are now more concerned about where their software comes from, how it’s built, and what other software is packaged inside the software they bought. With Iron Bank as the base image, there is a known and open source of the bottom layers of the container stack, including the system libraries and programs that are built on top of the operating system. 

Additionally, Cesium takes great care to analyze the JavaScript libraries we’re directly dependent on, as well as those that may be nested inside, to ensure that we are looking at what licenses the software is bundled with, if it contains any vulnerabilities, and if there are updates we should be using. To do this, we generate a Software Bill of Materials (SBOM) using Syft, which analyzes not just the software we’re using but also the dependencies of that software. Using those SBOMs and a tool called Grant, we can determine what licenses our dependencies have so that we can avoid any unfavorable licenses. A full view of what this scanning looks like is illustrated below. 

In addition to monitoring for CVEs, Cesium also continually monitors our software for security vulnerabilities through Static Application Security Testing (SAST) and secret scanning. SAST analyzes application code to identify potential security vulnerabilities that can be mitigated prior to release. It looks for things like SQL injection, cross-site scripting, and buffer overflows. Secret scanning helps ensure that authentication parameters are not stored in the code, containers, configuration files, or other areas in the released product. The reports generated from these tools allow us to harden our code and provide assurances to users about the security of the Cesium ion environment. 

Software security can be hard, and it’s important to be vigilant and confident in the measures taken to ensure your software and your users’ data are secure. In addition to vetting our own software, vetting containers and their stacks can be very complex. Fortunately, we can rely on a solid base with Iron Bank and use sophisticated tools from the open source community to ensure that we are always following security best practices. 

Use Cesium ion Self-Hosted to support corporate policies or create air-gapped solutions that meet strict security requirements and can be deployed to remote, disconnected environments. Learn more about using Cesium in your own environment. 

Cesium ion Uses Iron Bank Container Images for Software Security 

Author’s note: Many thanks to my colleague Jeshurun Hembd for his significant contributions to these results. This is part 2 in a series about visual quality improvements in CesiumJS; read part 1 here.

With the growing adoption of Cesium for Unreal and Cesium for Unity, developers of native applications have raised the bar for visual quality in Cesium apps. Specialized game engine features—like dynamic sun and sky lighting components, light probes, and global illumination systems—now can be applied to geospatial use cases. The CesiumJS squad has been working to bring browser-based geospatial apps to a new level with dynamic approaches to lighting.

glTF model of a polished metal sphere reflecting the environment, rendered in CesiumJS using improved image-based lighting and an HDR-image environment map.

Good lighting is essential to make the most out of physically based rendering, or PBR, a rendering technique common to both models and 3D Tiles. Think of a polished metal sphere: It’d appear flat and dull without anything interesting to reflect. To complement recent rendering improvements we’ve made to the glTF material model in CesiumJS, we’ve shipped several enhancements to our lighting system over the last few releases, including:

Refinements to the image-based lighting pipeline

New York Buildings 3D Tileset, rendered in CesiumJS with ambient occlusion before these lighting updates (left, version 1.121) and after (right, version 1.125). The overall effect of the changes is more realistic lighting and more easily understood model form.

There are many strategies for lighting, but one tried-and-true method that’s been a part of CesiumJS for several years is image-based lighting, or IBL. Lighting for glTF PBR models and 3D Tiles combines a single directional light source (i.e., the sun) and IBL to simulate a variety of dynamic lighting conditions, such as the precise position of the sun based on time and geospatial location or scattering of light through the atmosphere.

glTF model, courtesy of noe-3d.at on Sketchfab, rendered in CesiumJS with directional lighting (left), image-based lighting (middle), and a combination of directional and image-based lighting (right). The combination results in the most apparent dimension and sense of place when viewing the model.

IBL is an appealing approach because it simulates a complex lighting environment—like hemispheric lighting from the sky, diffuse reflections from the ground, and any other light sources in a scene—with a single environment map. This map encodes a high dynamic range of lighting info in an omnidirectional texture, typically with an HDR image supplied by the user or a procedural texture generated at runtime.

While users have been able to import their own environment maps, this required offline use of external tooling like Khronos’s glTF IBL Sampler for preprocessing, making it less accessible to those without a knowledge of lighting pipelines. With our recent work, we can now use dynamic environment maps in CesiumJS that adapt to changes in time of day, atmospheric conditions, or model positioning. This means CesiumJS developers get the full benefits of IBL without any additional configuration.

Created on the GPU, dynamic environment maps can be updated in near-real time to reflect the current sun position and model location. When time of day, atmosphere settings, or model position change significantly, the environment map can be updated in the background over a few frames.

The Damaged Helmet glTF sample model rendered in CesiumJS with default procedural lighting in version 1.121 (left) and with dynamic environment maps in version 1.125 (right).

For apps with more specific lighting needs, there are options that can be adjusted, like the overall intensity of the light or the color reflected by the ground.

Our existing shaders for simulating the sky atmosphere based on time of day were flexible enough to be reused by adapting the viewing angle to the model origin. This means we can simulate lighting conditions at sunrise or sunset but also high up in the atmosphere for aircraft and satellites.

A glTF model of a polished metal sphere reflecting the environment at morning (left), noon (middle), and evening (right), as rendered with dynamic environment maps in CesiumJS.

From the environment map, we can determine both the diffuse lighting as well as the specular reflections on any model or 3D tileset. For low-roughness materials like polished metals, the environment map can be used to look up the reflection coming from any particular direction. Rougher objects scatter light and therefore reflect light in a more diffuse way. To represent this, we need to compute the average light contribution across a range of angles representative of the degree of scattering, an operation which involves sampling the environment map hundreds, if not thousands, of times. 

To optimize runtime performance, we precompute values on the GPU when a model is first loaded and then store them in data structures for lookup at runtime. The environment map is stored as a cubemap for quick lookup based on the direction of the reflected ray. Specular maps corresponding to various material roughness levels are stored in texture mipmaps that are used to sample the specular radiance. Finally, diffuse irradiance—that is the sum of all incoming light for any particular direction—is represented with third-order spherical harmonic coefficients, a total of nine sets of RBG values.

Data structures used for IBL precomputed on the GPU in CesiumJS: From the environment map, a cubemap is created with each increasing mipmap level representing the specular reflections of materials with increasing roughness. The most diffuse lighting is stored as an array of spherical harmonic coefficients.

Another key improvement to our existing IBL implementation came from revisiting our cubemapping. We switched our environment map pipeline from octahedral projection mapping, a method which worked great as a stopgap solution in WebGL 1, to native cubemaps supported by WebGL 2. The simplified approach removed redundant work on the GPU and made it significantly easier to fix bugs with LOD selection for specular maps.

Ambient occlusion, or AO, is key for understanding the form and depth of untextured models, such as those seen in OSM Buildings data or architectural design models. This technique darkens areas which would receive less ambient or indirect light, like corners or creases, creating a look of soft shadows. We use a post-processing screenspace-based approach, which is applied to a scene after it has been rendered.

glTF model, courtesy of noe-3d.at on Sketchfab, rendered in CesiumJS with combined lighting effects. Ambient occlusion alone highlights detail in the model’s form. When combined with image-based and directional lighting, we can approximate effects similar to a global lighting system without the need for baking lighting or other preprocessing.

As part of this effort, we fixed existing bugs with our screenspace implementation of AO and enabled a new scalable solution for use across a variety of scenarios.

Horizon-based ambient occlusion, or HBAO, uses sampling to determine the minimum angle at which the sky hemisphere is no longer visible from a position. When this is repeated across multiple directions, we have an estimate about the percentage of light in the scene that reaches each pixel. This technique helps visually communicate depth, form, and spatial proximity between objects in the scene, and it can be performed in screenspace for better runtime performance without the need to precompute lighting.

The key improvement made in our implementation was enhanced scalability. While typical AO use cases, like games or architectural visualization, are constrained to one scale, CesiumJS users can travel from outer space to underground in a single app. Previously, the AO parameters had to be configured manually based on trial and error to balance visual appearance with runtime performance. This was inconvenient for anything other than a specific view.

The limitation was the step size used to march along each sampling ray. Rather than using a fixed distance measured in meters, we implemented a normalized Gaussian distribution to scale the sample distance based on the distance from the camera, removing the need for any manual configuration. Occlusion now scales effectively from detailed interiors like pipes in a power plant to large cityscapes like buildings in New York City. Additionally, the falloff is now much smoother: As distance from the camera increases, the shadowed areas become wider, but less dark. In effect, it’s a much closer approximation of how light is occluded in reality.

glTF model, courtesy of noe-3d.at on Sketchfab, rendered in CesiumJS with ambient occlusion only. Scaling the sampling distance ensures views of the model at any scale, by default and without adjusting any settings.

We are committed to continuously pushing the boundaries of what can be achieved with browser-based 3D to provide users with better visualizations. The recent updates to IBL, dynamic environment maps, and ambient occlusion have been a few major steps in that journey.

glTF model showcasing diffuse lighting, courtesy of noe-3d.at on Sketchfab, rendered in CesiumJS before these lighting updates (left, version 1.121) and after (right, version 1.125). The overall effect of the changes is more realistic lighting and more apparent fine details.

Our efforts to enhance the visual quality of CesiumJS are always ongoing. We generated many ideas during this process—like an easier-to-use API for using HDR images and enhancements to how we render shadows—but your feedback is invaluable as we strive to further improve CesiumJS. Check out the Sandcastle example used throughout this blog, and please share your input on visual quality in this community thread.

Leveling Up Lighting in CesiumJS: IBL, Dynamic Environment Maps, and Ambient Occlusion

Code review is at the heart of what we do at Cesium. In this blog we discuss core principles around our review process and introduce our code review guide, which we recently created and made available in our new public community repo. At Cesium we maintain multiple open source repositories, most notably our runtime libraries for visualizing geospatial graphics on the web (CesiumJS) and via native engines (Cesium Native, Cesium for Unreal, Cesium for Unity, and Cesium for Omniverse), and since 2012 we have been making monthly releases of these libraries. CesiumJS alone has close to 250,000 lines of source code and 280,000 lines of test code. We also maintain Cesium ion SaaS and Cesium ion Self-Hosted, platforms for tiling, hosting, and streaming 3D geospatial data as 3D Tiles. To top it off, Cesium projects are built collaboratively between the community and the core team, with more than 300 external contributors committing source code to CesiumJS and dozens contributing commits to our native runtimes. 

Maintaining projects at this scale and in open source is not possible without strong engineering processes. Pull requests (PRs) and code reviews—more than most any other engineering process—are where rules are enforced and culture is built. Cesium has structured our guide to reinforce the core values of our engineering teams: Enhance code quality and consistency, streamline collaboration, facilitate knowledge sharing, and foster shared ownership. You may notice our guide doesn’t drill deep into language and framework-specific practices; we designed it as an overarching framework that can be augmented with specific tooling or style guides for our individual projects.

Here are the key principles at work in our guide. 

Tone: Seek great code and motivated people

We often say, "comments are about the code, not the people." We believe review comments are positive opportunities to discuss and improve. Our guide suggests using guiding questions and presenting evidence. Questions invite discussion and are a more gentle way to suggest changes. Every suggestion should be able to link to an authoritative source, like the project's coding guide, rather than relying on the reviewer's opinion. Empathy on the reviewer's part can go a long way toward keeping the contributor motivated in the review process.


Code review cannot happen without well organized projects, and we lean heavily on Git to organize our engineering projects. Git branches and branch protection rules enable collaboration and help us avoid forcing work in progress upon others before it's ready. Our guide advises keeping branches as focused as possible, avoiding mixing large-scale, cross-cutting changes with other changes. We suggest breaking complex changes into a sequence of smaller pull requests, each of which builds upon the previous. Lastly, we caution to avoid rebasing to preserve a usable version history.


Open timely and scoped PRs that create a historical record

We believe PRs should be small, targeted, and atomic. The PR author should create tasks lists covering and linking to all additional work required before merging. Team members should start code review and respond promptly (within 24 hours) to maintain momentum and investment from the author. Pull requests serve as a historical record of a change, so it is important to document the context of the pull request to help preserve it for future reference. The author should include why the change is being made and the test plan with steps and configuration needed to verify the change. Linking is an effective tool for documenting context: We create links to relevant issues (in the current repository or other projects), community forum posts or support threads, standards or API documentation, changelogs for dependencies, and best practices, such as blogs or guides.


Communicate status with automation, CI, and GitHub tooling

No matter the project, our guide advises using Github Actions workflows as part of continuous integration (CI) processes to enforce style guidelines through linting, code quality through unit tests and code scanning, and security through secrets checking and vulnerability scanning. The specific implementations of these checks depend entirely on the language and other features of the project, but automating them, as our guide recommends, streamlines and strengthens the code review process. The reviewer should ensure all checks pass and check artifacts for each stage to ensure that there are no “silent failures.”

Reviewers should maintain velocity by being concise and direct in their comments, avoiding the temptation to expand scope of the PR, and always trying to level up the team by providing impactful feedback that will then be sought after by other engineers. Our guide provides an overview of the critical areas a reviewer should look at before approving a PR, including design, execution, performance, complexity, third-party libraries, style, tests, and documentation of the code changes. 

Approving and merging a pull request means that the reviewer is accepting some responsibility for the code being merged. The author of the code is still largely accountable for any critical issues that immediately arise, but the reviewer shares some accountability as well. In practice, reviews differ by level of toughness depending on the change, which we thought was valuable to break as follows:

Rubber stamp: suitable for pull requests that only deal with documentation.

Skim the code and ensure all CI automation is passing: suitable for small pull requests.

Compile locally and run the code: suitable for most pull requests.

Deep read of the code changes: suitable for most large pull requests.

Synchronously review one-to-one with the author: suitable for giant pull requests.

Lastly, reviews should be public. If the reviewer and author meet in a video call or in a room, the reviewer should summarize the discussion in a PR comment. This helps everyone looking at the PR later and ensures we are transparent about the life of the PR.

Our guide calls out important steps embedded in our code review process for maintaining consistency and usability of our public APIs. Changelogs and release notes should provide clear and open communication about project updates, while also managing user expectations and promoting new features. The code review should ensure the PR meets the following expectations critical for public facing APIs:

Have a versioning strategy: If the changes are significant or potentially break backward compatibility, verify that the project is prepared for a version bump in accordance with its versioning strategy, e.g., according to semantic versioning principles.

Highlight deprecations and breaking changes: Clearly mark any deprecations or breaking changes in the PR description.

It is sometimes necessary to reject a pull request, in particular to maintain the project’s scope. When doing so, first begin with thanks and acknowledge the contributor’s needs as valid, even if the contribution doesn’t align with the project’s goals. Then be clear and constructive about why the PR does not fit with the project. Following that, present the author with ways out, such as a workaround or forking the repo. And finally, encourage them to contribute again in the future.  

Our code review guide is a living document that can be edited and expanded as needed, so it can and will change over time. Cesium has designed our guide to be a forward-looking overarching framework, which can then be implemented as specific guides for individual projects. 

We invite anyone to open issues with feedback or submit PRs with suggestions about our new guide in our community repo, which houses the guide on GitHub.

Building Culture and Community with Code Reviews

In November 2023, we announced the Reality Tiler that replaced our then-current photogrammetry tiler as part of the 3D Tiling Pipelines included in Cesium ion and Self-Hosted products. We built the Reality Tiler with emphasis on scalability, tiling performance, and runtime efficiency. Today, we’re digging into Reality Tiler v2, released in July 2024. We’ll cover the complete refactor of the Reality Tiler, where we rebuilt the tiling pipeline from the ground up, bringing significant improvements to tiling time, tileset quality, and runtime performance. We’ll take a close look at memory and runtime performance metrics and end with next steps for further improvements and optimizations.

Before we dive in, note that the Reality Tiler primarily operates on photogrammetry models or models reconstructed from LiDAR scans, potentially massive in scale. These models typically consist of explicit geometry, e.g., a triangle mesh, and color texture information.

The first version of the Reality Tiler operated by iteratively simplifying and subdividing the entire input model.

Reality Tiler v1 flow: simplification, subdivision, and tile generation.

Although the Tiler made use of out-of-core techniques to ensure that we didn’t run out of memory, it had two shortcomings. First, data access patterns were incoherent. When generating tiles or simplifying the model, the data needed for a series of operations were not coalesced into contiguous memory blocks, resulting in frequent cache misses and requiring unnecessary paging between disk and RAM. These types of access patterns can slow down processing, sometimes substantially.

The second shortcoming of that approach is that it created a fixed number of levels of detail (LODs) across the board. It is a reasonable approach for models that are relatively uniform, but some models aren’t uniform. In practice, many models have areas of higher detail and areas of lower detail. For example, parts of a model may have much higher triangle density than others or use higher resolution textures. A fixed number of LODs can create unbalanced tilesets, with some tiles containing too much information and other tiles containing too little. At runtime, this translates to inconsistent performance: Too many large tiles leads to lower framerates, and too many small tiles can result in excessive network requests and slow streaming.

Reality Tiler v1 created uniform tilesets. Notice how the tree is balanced but some tiles are larger than others.

We considered several strategies to address the shortcomings of Reality Tiler v1, but we ultimately decided to flip the entire process on its head. Rather than taking a global approach—which is to say, operating on the entire model when producing tiles and performing simplification—we take a local approach and process only one part of the model at a time. More specifically, Reality Tiler v2 splits the model into leaf tiles and builds the tileset by iteratively merging and simplifying tiles until we are left with a single root tile. Because individual tiles are relatively small and mostly contiguous in memory, data access is much more coherent, and, consequently, the overall process is significantly faster.

Reality Tiler v2 flow: subdivision, mergers, simplification, and tile generation.

With Reality Tiler v2, we ensure that each leaf tile is approximately the same size (in terms of geometry and texture content, not extent in world-space). This means that certain parts of the input model with dense geometry or texture data may be tiled more deeply than others, and tiles further up the tree remain approximately uniform in size.

Reality Tiler v2 creates uniform tiles. Notice how the tree is unbalanced but the size of each tile is the same.

By switching to this new, local tiling approach, we see dramatic improvements in tiling performance and memory usage. Here’s a look at the results for a few datasets. (All tests were run on a machine with 256GB of RAM, 64 logical CPU cores, and a 4TB NVMe drive.)

**Reality Tiler Tiling Time Comparison**

Dataset           |Triangle Count (Millions)         |Prev. Tiling Time (h:mm:ss)|New Tiling Time (h:mm:ss)|Percent Reduction in Tiling Time
---------------------|------------|----------|----------|-----------
Carrick Hill (Australia)                 |3.3|0:02:37       |0:01:11       |55% |
Liverpool (UK)|7.8        |0:08:48       |0:02:54 | 67%|
Budapest (Hungary)                 |43.1|0:59:05      |0:14:08       |76%|
Melbourne (Australia)		|69.9|3:22:41|0:27:58|86%|



**Reality Tiler Memory Usage Comparison**

Dataset           |Triangle Count (Millions)         |Prev. Peak Memory (GB)|New Peak Memory (GB)
-----------------------|-----------|---------|-----------
Carrick Hill (Australia)                 |3.3|13.5     |14.9    |
Liverpool (UK)|7.8        |22.1    |22.7 |
Budapest (Hungary)                 |43.1|61.7    |21.3|
Melbourne (Australia)		|69.9|134.5|26.9|


Reality Tiler v2 tiling time is reduced across the board, about 2-7 times faster than Reality Tiler v1. Generally, the larger the input, the greater the speedup. Memory requirement trends have similar gains, with the largest datasets seeing the greatest reduction in peak memory usage (for smaller datasets, we see a slight increase in memory usage for these samples). Taken together, these improvements indicate substantially improved scalability for the Reality Tiler: It’s able to process more data in a shorter period of time, while typically using less memory.

Because of non-uniform tiling, we also see a reduction in the variation of file sizes for tiles. Melbourne, Australia, for example, is a dataset that does not have uniformly sized triangles, and therefore it particularly benefits from non-uniform tiling.

A wireframe view of a portion of Melbourne. Notice the variation in triangle size and density: The buildings (upper left) have small and densely packed triangles, while the triangles that make up the river (lower right) are much larger.

With Reality Tiler v1, which tiles uniformly, Melbourne’s average tile size was 1.28 MB, with a standard deviation of 706 KB. For v2, the average tile size is 395 KB, with a standard deviation of 192 KB.

We’ve come a long way since the v1 release of the Reality Tiler, and we still have a number of ideas for future enhancements. The two largest bottlenecks in our pipeline are now texture compression and texture coordinate generation. We will likely focus on both in the near future.

We will also work to bring down peak memory usage even further. Although mesh data is mostly handled out of core, the data structures that help us index into it reside in memory. We plan to adapt this structure to also not entirely reside in memory.

Interested in using the updated Reality Tiler? Sign in to your Cesium ion account or sign up and get started for free!

Reality Tiler V2 Improves Tiling Time and Memory Usage

Cesium ion SaaS handles a wide range of functions and serves a global user base, requiring rapid updates and bug fixes. To deliver at this pace, Cesium minimizes the time developers spend away from feature development. An automated testing and deployment pipeline is key: It allows developers to focus on adding value for users while automation handles the operational aspects of deployment.

Although setting up an automated CI/CD (continuous integration/continuous deployment) pipeline involves a large up-front investment in engineering resources, the long-term benefits are substantial. The efficiency gained through reduced development friction and accelerated deployment far outweighs the initial cost. In this blog, we share Cesium ion’s automated CI/CD pipeline, which closely follows AWS’s recommended practice and enables several deployments a day. This enhances our ability to deliver consistent value to our users.

The first step is to run automated tests, which include unit and end-to-end tests, to ensure the new code is up to our engineering standards. Our CI infrastructure, powered by Github Actions, is responsible for running these tests for every commit on all repositories that are part of ion. Beyond testing, GitHub Actions also handles code containerization, linting, and automated security scanning. The extensive coverage of these automated tasks enables us to ensure each commit is a deployment-ready update to Cesium ion.

Once the above CI checks pass on a pull request, and the code has been through a pull request review process, the next step is to execute our CD pipelines. Cesium ion operates three deployment environments: development, staging, and production. We manage these environments with two distinct CD pipelines. We use a branching strategy for our repositories, in which the main branch always contains the latest changes, while the production branch represents what has been deployed. Changes to the development environment are automatically deployed with every merge to the main branch, providing us with an always up-to-date environment to test the latest functionality. Because the CI directly kicks off the development environment pipeline, it is easy to point the development pipeline to a feature branch and deploy it to do testing in a realistic environment before merging the code to main. The second pipeline manages deployments to staging and production. It is triggered automatically anytime a commit is made to the production branch in any one of our repositories. See the graphic below for details about how these pipelines deploy:

Deployment pipeline for infrastructure and application code for Cesium ion SaaS.

The containerized images from the above CI steps are pushed to AWS Elastic Container Registry (ECR) for deployment. In the development environment, these images are directly pushed to the development AWS account. For staging and production environments, the images are pushed to a “SharedServices” AWS account, which manages cross-account permissions and deployment processes. 

All of the infrastructure within our AWS accounts is stored in AWS CloudFormation templates (Infrastructure as Code). The CD pipeline also updates various AWS components, including policies, alarms, notification topics for services like RDS PostgresQL, Elastic Container Service (ECS) clusters, Route 53, AWS WAF, CloudFront, and AWS Batch. These CloudFormation templates are deployed to the respective AWS account through the CI in the infrastructure repository. Updates to these container images in ECR or CloudFormation templates trigger an AWS CodePipeline execution. The pipeline uses the new images to update the AWS ECS cluster and the CloudFormation templates to update policies and infrastructure settings. The pipeline first applies necessary infrastructure updates before deploying the updated images to AWS ECS. We have automated rollbacks and alerts configured to address any issues if a new container instance fails to start. 

The development and staging pipeline, managed by “SharedServices,” first pushes all updates out to staging, and then, as a second step, performs the updates in production. For quality control, we have included a review step between the staging and production deployments, though our setup allows for automated production deployment if necessary. In addition to managing container images and infrastructure updates, our CD pipeline performs several other tasks. For our front end, which consists of statically hosted files, the pipeline handles compilation and transpilation during CI, with the files then pushed directly to the respective accounts. For our AWS Lambda and Lambda@Edge functions, the pipeline generates a hash based on the function code and compares it with the existing production version. If there is a mismatch, the updated lambda function is pushed when the pipeline is triggered. The primary reason for doing deployments only when we detect code changes is to speed up overall deploy time.

With our streamlined process, deploying changes to Cesium ion SaaS is extremely easy. Developers simply need to merge changes to main and production branches of the respective repositories, click a button, and make the feature available to millions of users worldwide.

Experience features from the advanced pipeline by signing up or signing in to your Cesium ion account.

Author’s note: Many thanks to my colleague Jeshurun Hembd for his significant contributions to these results.

To elevate the look of Cesium apps on the web, we’ve shipped key updates to glTF rendering over the past few CesiumJS releases, including improvements to the glTF physically based rendering (PBR) material model and tone mapping. 

We've focused our efforts on enhancing the initial impressions of glTF and 3D Tiles, particularly for visualizations where a diverse array of material types can significantly impact the digital representation. We're aiming for more than just pretty pictures—fundamentally our goal is to improve the user's understanding of complex 3D geospatial scenes. Lastly, we are committed to ensuring consistent model appearances with other apps in the glTF and 3D Tiles ecosystem, essential for data portability across different platforms and products.

glTF modern office by Kerkstra Precast via Sketchfab, in CesiumJS with updated PBR material model, tone mapping, and lighting.

Achieving a balance among visual quality, performance, and accuracy in a web-based environment like CesiumJS presents a unique set of challenges.

Browser-based limitations: Unlike native applications such as Unreal Engine or Unity, CesiumJS operates within the constraints of a browser. This impacts how much control we have over optimizing graphics processing and memory usage.

Runtime data streaming: In geospatial apps like CesiumJS, data is streamed at runtime rather than a designer constructing a pre-authored level with detailed lighting information. Since dynamic adjustments and computations at runtime are required, performance is top of mind.

Scalability and precision: CesiumJS is designed to handle millimeter-precision data up to global extents and from underground perspectives to views of outer space. Determining default parameters without losing detail or performance proves tricky.

During this push for better visual quality, our ubiquitous use of glTF was a huge asset. CesiumJS renders models with .gltf or .glb files and 3D Tiles which directly link to .gltf or .glb files. Working within the glTF ecosystem provided us with foundational tools, particularly an extensive library of sample models and open source reference implementations, such as the PBR shaders available in the glTF-Sample-Viewer repo from Khronos.

Let’s discuss the impact the improvements to the PBR material model and tone mapping have on glTF rendering in CesiumJS.

glTF 2.0 introduced physically based rendering (PBR) as a core feature, allowing for a simple, standard set of parameters to simulate real-world lighting interactions, materials, and surface properties. With PBR, a developer or artist without knowledge of rendering pipelines or shaders can build a material that accurately responds to lighting conditions, reflections, and shadows.

Key fixes and updates were to reflective properties of a physically based material in CesiumJS. 

Updated the bidirectional reflectance distribution function (BRDF), a function that defines how incoming light interacts with opaque surfaces, from a Schlick-Smith approximation model to a microfacet-based model yielding more physically plausible results.

Added approximate multiple scattering for diffuse light and reflectivity fixes, ensuring better energy conservation when light is scattered or reflected off of a surface.

These updates result in brighter looking models—good news, as we were seeing complaints of glTF models rendering too dark—and more consistency with the rest of the glTF ecosystem. Moreover, these updates greatly improved the appearance models with supported glTF PBR Next extensions recently implemented in CesiumJS: KHR_materials_specular extension, KHR_materials_anisotropy extension, and  KHR_materials_clearcoat extension.

After: Pot of Coals glTF sample model. Note the more realistic specular highlight on the burnt copper surface, improved reflectivity at grazing angles, and overall increased brightness of the model.

Tone mappers come into play as a last step of the PBR rendering process. They are functions that scale PBR output—linear values approximating real-world light energy, which may range orders of magnitude beyond what a monitor can display—down to a smaller device output range. 

CesiumJS previously tone mapped models, atmosphere, and the globe using ACES, a film industry standard but one that could often result in desaturated, dimmed appearances. We’ve replaced our default with the Khronos standard PBR Neutral Tone Mapper. That means more consistency of color appearance across the glTF ecosystem, which includes e-commerce vendors for whom accurate color representation is essential.

This new tone mapper widens the gamut of possible displayed colors and, in particular, helps brighten and slightly staurate the appearance of many models.

Left: Cesium Air glTF model with ACES tone mapping. Right: Cesium Air glTF model with Khronos PBR Neutral tone mapping. Note the brighter whites and more saturated greens and blues.

Left: San Miguel 3D Tileset with ACES tone mapping. Right: San Miguel 3D Tileset with Khronos PBR Neutral tone mapping. Note the brighter whites and more saturated greens and blues.

As we continue to build upon CesiumJS's visual capabilities, our enhancements to the PBR material model and the introduction of the Khronos PBR Neutral Tone Mapper have already gone a long way to improving our browser-based rendering quality. These updates enhance scene realism and consistency, address user feedback about dark models, and more closely align with standards of the glTF ecosystem.

Stay tuned for our next blog post on CesiumJS visual quality, which will focus on steps we’ve taken to enhance lighting and better match the current environment.

We encourage you to explore these updates and share your feedback in this community thread. Your insights are crucial as we continue to refine the visual quality of CesiumJS.

Leveling Up glTF Rendering in CesiumJS: PBR Improvements and Khronos Neutral Tone Mapping

3DTilesRendererJS is a library originally developed at NASA/Caltech-JPL for rendering 3D Tiles  in Three.js. The project was released as open source and is now maintained by Garrett Johnson, who worked there for more than a decade. 

In April 2024 Garrett Johnson was awarded a Cesium Ecosystem Grant to expand support in 3DTilesRendererJS for new 3D Tiles metadata extensions and to enable data overlays useful for understanding 3D Tiles Mars terrain data from NASA JPL. Those improvements have now been implemented; this post by Garrett describes the work completed.

This year I was grateful to have been awarded a Cesium Ecosystem Grant to enhance 3DTilesRendererJS, an open source library originally developed by NASA/Caltech-JPL (Jet Propulsion Laboratory) for rendering JPL-generated Martian datasets. The project enables efficient rendering and interaction of 3D Tiles in Three.js, an open-source, cross-browser JavaScript library for 3D graphics in a browser. Thanks to the work supported by the grant, the library now supports glTF metadata extensions from 3D Tiles 1.1 and alternate tile texture overlays. These new features will enable end users to implement more robust AEC and GIS applications with 3D Tiles and Three.js. 


3DTilesRendererJS now supports the glTF `EXT_structural_metadata` and `EXT_mesh_features` extensions. The mesh features extension allows for parsing and reading associated IDs with varying levels of granularity in a model, which can subsequently be used for looking up more complete data. And the structural metadata extension gives users the ability to look up detailed, structured data based on embedded identifiers, including those from mesh features.

Visualization of structural metadata and mesh features from 3D Tiles 1.1 is now possible in Three.js with the San Francisco Ferry Building.

The plugins for the `EXT_structural_metadata` and `EXT_mesh_features` extensions compatible with Three.js’ `GLTFLoader` are located in the [src/three/loaders/gltf](https://github.com/NASA-AMMOS/3DTilesRendererJS/tree/master/src/three/loaders/gltf) project directory, along with associated type definitions exported from the package. To use the plugins they must be registered to a `GLTFLoader` instance used for loading the files after creating the `TilesRenderer` instance for loading a tileset:

```javascript
import { 
    TilesRenderer, 
    GLTFMeshFeaturesExtension, 
    GLTFStructuralMetadataExtension, 
} from '3d-tiles-renderer';

// ... 

// Create a tiles renderer and intialize a GLTFLoader with both
// metadata extensions

const tiles = new TilesRenderer( url );
const loader = new GLTFLoader( tiles.manager );
loader.register( () => new GLTFMeshFeaturesExtension() );
loader.register( () => new GLTFStructuralMetadataExtension() );
tiles.manager.addHandler( /(gltf|glb)$/g, loader );
```

Once the tiles are loaded the data from the extensions can be accessed via the `meshFeatures` and `structuralMetadata` fields in the associated objects' `userData`. These fields can be accessed when hovering over or clicking on a tile after a raycast, for example, to display metadata tables or highlight the object by id:

```javascript
const triangle = new THREE.Triangle();
const barycoord = new THREE.Vector3();
const invertedMatrix = new THREE.Matrix4();
domElement.addEventListener( e => {
    
    // ... set up raycaster
    
    const hits = raycaster.intersectObject( scene ); 
    if ( hits.length > 0 ) {
        
        const { object, face, point, faceIndex } = hits[ 0 ];
        
        // ... calculate the barycoord of the point on the geometry face
        
        const { meshFeatures, structuralMetadata } = object.userData;
        if ( meshFeatures && structuralMetadata ) {
            
            // get the metadata features and property table indices
            const features = meshFeatures 
                .getFeaturesAsync( faceIndex, barycoord );
            const tableIndices = meshFeatures 
                .getFeatureInfo().map( info => info.propertyTable );
                
            // read and log the structural metadata
            const data = structuralMetadata 
                .getPropertyTableData( tableIndices, features ); 
            console.log( data );

        }
        
    }

} );
```

Two 3D Tiles datasets from Cesium ion are available for demonstration here; to use the demo please retrieve the trial ion access token from the Cesium repository. Refer to the example implementation for code showing how to use custom materials for tileset brushing and reading data, and see supporting documentation for API documentation and function definitions.


To support the implementation of the new extensions, a variety of contributions were made to the broader Three.js ecosystem to enable improved performance for reading data from textures and to add new math utilities. Changes were made to allow copying texture subframe data to the GPU to avoid stalls from uploading a whole texture. This allows for only uploading and reading a single pixel of data so it can be quickly read back when querying mesh features and structural metadata textures without blocking page interactivity.

Likewise, thanks to initial work from @sciecode on Github, GPU texture data buffers can now be read back to the CPU asynchronously in Three.js. This is used for reading texture-encoded metadata values without waiting for remaining GPU work to complete, allowing for a significantly smoother user experience when reading the values.

And lastly, a new Matrix2 core math data type has been added to the library. Matrix2 is a type supported by glTF and WebGL vertex attributes, in addition to being used to store metadata values and is now available to be used and expanded on in Three.js.

At NASA JPL, texture overlays are used on top of terrain geometry to help provide more context for robotics and science operations. The texture overlay plugin is designed to support loading one or more replacement textures for a set of tiles to display alternate data overlays–including properties like slope, roughness, or error metrics. This feature will extend to other pre-processed texture data visualizations for photogrammetric tilesets should they provide alternate textures per-tile. By providing the ability to replace textures for the full tileset rather than using a 2D projection, overlay detail can be included across the full extent of the tileset, including concave geometry surfaces. For this demonstration a Martian tileset was produced using NASA JPL tools and data from the Mars 2020 mission using slope magnitude as an example overlay. In practice NASA JPL uses a variety of these kinds of precomputed texture skins to aid with operations on Mars, including displays for robotic kinematic reachability or surface roughness.

Check out the demo for the data overlay, which shows loading ten wedge tilesets with slope magnitude overlay textures. One or more of these alternate textures can be blended with the original using custom shaders or used as opaque replacement textures for the tiles.

Texture overlay of Mars data showing multiple sets of overlays including slope magnitude. Left: original textures, center: blended slope visualization, right: opaque slope texture overlay.

To produce a sample dataset for this feature and ensure functionality for the practical operational use case, the open source NASA-AMMOS/Landform project, used internally by JPL to generate merged and per-wedge 3D Tiles datasets for Mars 2020 missions operations, was used to generate the sample terrain. Color imagery and alternate image products from the official NASA JPL Planetary Data Systems (PDS) data archive were used, which hosts historical data from a variety of NASA missions for download. For the sake of demonstration only a single alternate set of textures highlighting slope magnitude have been produced, though other alternate textures can be generated from available PDS data.

Documentation for the TilesOverlayPlugin is available on the plugins documentation page. If your dataset contains alternate sets of textures, the plugin can be instantiated and textures applied to tiles materials like so:

```javascript

import { Tiles Renderer } from '3d-tiles-renderer';
import { TextureOverlayPlugin } from './examples/plugins/TextureOverlayPlugin.js';

// ... 

const tiles = new TilesRenderer ( url );
const plugin = new TextureOverlayPlugin( {
    textureUpdateCallback: ( scene, tile, plugin ) => {
        
        // Retrieve the loaded texture layers for this tile
        const slopeTexture = plugin.getTexturesForTile( tile ).slope;
        scene.traverse( child => {
            
            if ( child.isMesh ) {
                
                // Replace the original texture with the new one 
                child.material.map = textures.slope;
            
            }
        
        } );

    },
} );

// Set up a new layer textures to trigger when a new tile geometry is loaded
plugin.registerLayer( 'slope', url => {
    
    // Adjust the tile geometry url to load the associated texture
    const url = tileUrl 
        .replace( '/tilesets/', '/textures/slope/' ) 
        .replace( /\.glb$/i, '.png' );
        
    // Load the texture and fix the texture settings
    return new TextureLoader()
        .loadAsync( url )
        .then( tex => {
            
            tex.colorSpace SRGBColorSpace;
            tex.flipY = false;
            return tex;
        
        } );
    
} );

tiles.registerPlugin( plugin );
```

To support this work, a new extensible plugin system was added to the `TilesRenderer` class, which has subsequently been used for the development of other new plug-and-play features for 3D Tiles.

The addition of a new TilesRenderer plugin system for tile overlays has enabled a new addon architecture for 3D Tiles rendering. Previously a full subclass of the TilesRenderer class would need to be made, making it very difficult and brittle to use multiple extended classes at once. 

The new TilesFadePlugin has been added to smooth the transition between tile levels of detail by modifying materials to add dither animation when fading in and out. The TilesCompressionPlugin compresses loaded tile geometry data and reduces texture mipmap usage, which can improve GPU memory usage by over 30% in some cases. And the UpdateOnChangePlugin can improve performance per frame by only triggering tileset traversal when the camera or tileset has changed.


These plugins and others are available in the examples and core directory of the project. In the future, plugins could be added for other features including Three.js BatchedMesh support, tile geometry modification, new 3D Tiles features, and other user plugins.

With the work enabled by this grant the NASA-AMMOS/3DTilesRendererJS project now supports a variety of new features expanding the utility for scientific as well as architectural use cases. The tiles renderer project has benefited greatly from reports and contributions from the community to improve it over time so please feel free to provide feedback on the new features and try it out and let us know what you think.

Learn more about the Cesium Ecosystem Grants program and other ways Cesium engages with the broader community to see how you can get involved. 

Enhancements to the Three.js 3D Tiles Renderer

Globe view of UNICiv, showing sites from 1800 BCE - 1500 CE. The Legananny Dolmen in Ireland is selected.

Interactive digital maps display detailed contemporary geographic information, increasingly in 3D, for navigation, exploration, and virtual travel. What the world looked like near the beginnings of human civilization, however, is more difficult to discover, search, and visualize. Cesium Research’s most recent publication, UNICiv: A Universal Navigation Interface to Civilization, explores Cesium’s ability to support 3D models of ancient and historic sites within their geographical and temporal context.

Developed over the summer by Cesium's Yuhan Liu and led by Dr. Norman Badler, Head of Research, UNICiv is an extensible, universal, spatio-temporal interface that leverages Cesium for Unreal and 3D Tiles to visualize structures of the distant past. As a demonstration and education tool, UNICiv’s applications range from cultural heritage to urban planning. The UNICiv publication has been accepted as a full research paper to the Eurographics Workshop on Graphics and Cultural Heritage (GCH 2024). 

GCH is the premier technical meeting for novel digital technologies in the cultural heritage domain, fostering discussions in AI, Computer Graphics, Computer Vision, and Human-Computer Interaction.

UNICiv offers over 30 explorable 3D models of historic and archaeological sites around the world, displayed collectively on a single interactive globe. These models are produced by archaeologists, independent artists, or research projects from institutions and nonprofits. Sites range in time from 8000 BCE to 1500 CE. Examples include Neolithic monuments like Stonehenge, ruins of Bronze Age villages, and Greco-Roman temples. These models have been curated and imported into Cesium for Unreal through Cesium’s integration with Sketchfab. The models are imported into Unreal using Cesium’s plugin and placed on top of Cesium World Terrain with Bing Maps Aerial imagery.

Users can explore the past in 3D using UNICiv’s interface. Start by navigating a Cesium globe where ancient structures are highlighted as pins. The timeline interface indexes sites that appear on the globe. When users select a site, they are taken on a flight path to its geolocated model, where they can use traditional game controls to explore. Users can build their personalized list of sites to save, compare, and present their findings. Additionally, some locations offer reconstructed visualizations that can be overlaid on current-day ruins, providing a unique perspective on how these ancient sites once appeared.

Perspective view of the reconstructed Old Temple at Pachacamac in Peru. Site list controls set to Common Era (0-1500 CE). Cesium World Terrain shows the present-day view of the Lima Province. Model courtesy of Aline Normoyle, Clark Erickson, and Norman Badler, used with permission.

La Motilla del Azuer, 3D Model from Global Digital Heritage on SketchFab. Tour site list shows manually added fortification sites.

Amphitheatre of Butrint, 3D Model by Ørjan Sandland, imported from Sketchfab (CC Attribution). Simultaneous Site List shows all sites with reconstructions (not pictured) available to view. The Albanian mountains are part of Cesium World Terrain with Bing Maps Aerial Imagery.

Temple of Apollo - Naxos Greece, 3D Model by Vasilis Haroupas on SketchFab. Simultaneous Site List shows all available BCE models. Terrain from Cesium World Terrain with Bing Maps Aerial Imagery.

From incorporating more models to iterating on user experience, UNICiv is an ongoing research project with exciting directions for future work. A significant task for the future would be to incorporate and reverse-engineer significant geographical changes to experience the natural environment experienced by the earth’s earliest inhabitants. In the meantime, UNICiv provides a uniform, 3D geospatial, contextualized interface to the re-discovered past.

The UNICiv publication was one of eight full research papers accepted to the 22nd Eurographics Workshop on Graphics and Cultural Heritage 2024. The Cesium research team is excited to present at the conference, which takes place September 16–18, 2024, in Darmstadt, Germany.

UNICiv is a powerful tool for visualizing temporal change on a global scale, especially in cultural and historical preservation. Initial user evaluations have highlighted UNICiv’s significant potential for advancing archaeological demonstration, education, and exploration. Furthermore, the UNICiv interface becomes increasingly adept at capturing the development of human civilization as more 3D models are integrated into it. Thus, the Cesium research team plans to soon provide open access to the UNICiv resource and welcomes collaborations and user contributions. Contact Dr. Norm Badler to express your interest in UNICiv.  

For help getting started on your own project with Cesium for Unreal, visit the Learning Center. 

Cesium Research's Universal Navigation Interface to Civilization (UNICiv) Accepted for Publication and Presentation at Eurographics Conference

Pull requests and code reviews are an intrinsic part of software development at Cesium, but they can also be one of the most challenging and time-consuming aspects. Our continuous integration (CI) processes aim to automate developer overhead, improve code quality, and increase confidence in our monthly releases before any code goes into the main branch. Every code commit is automatically built and tested, catching conflicts or errors early in development so developers can resolve them quickly. 

As maintainers of a large open-source project like CesiumJS, we face somewhat unique challenges in comparison to most codebases. To start, the JavaScript library for 3D geospatial visualization is extensive–just under 250,000 lines of source code and over 275,000 lines of test code. We must ensure code quality and consistency across contributions from a diverse group of external developers, and across a heterogeneous codebase consisting of JavaScript, HTML, GLSL, TypeScript definitions, API reference docs, developer docs, and more.

Since we initially set up the first CesiumJS CI pipeline using Travis CI, the demands on that pipeline have grown. We’ve replaced outdated build tooling, expanded quality checks, and added additional workflows. While Travis CI served us well in the early stages, Cesium grew as an organization and we started to run into scalability challenges: cost, speed, and fragmentation in CI tools used across different teams. 

Since Cesium was already deeply integrated with GitHub for issue tracking and code reviews, switching to GitHub Actions streamlined our processes. This move across the organization allowed the CesiumJS repo in particular to speed up our CI runs and to implement reusable actions across our repositories.

In our CI workflow, we focus on efficiency by running multiple jobs in parallel. This approach helps us speed up the integration process and ensures comprehensive coverage across key areas of development. 

Diagram of the CesiumJS CI process using GitHub Actions to run multiple jobs in parallel.

The status of each job is shown in the PR using commit statuses, signaling to the reviewer that the PR should not be merged until all jobs pass. Build artifacts such as logs, coverage results, and deployments are linked for easy access by the developer and reviewer.

Status results display in each PR, so status is immediately understood.

Automated builds confirm the project's stability. 

We bundle the JavaScript source code into two main distributions that are shipped with CesiumJS: 1) a developer build, unminified and designed for debugging, and 2) the production release build, which is fine-tuned for performance, including minification and stripping debug pragmas. Using esbuild for bundling allows us to reduce our build times, enabling quicker iterations without sacrificing quality.

Running the custom script to generate the release zip file is valuable as it contains the two distributions, developer documentation, and tools like Sandcastle, helpful for developers to test functionality and experiment with CesiumJS. 

We also generate the npm package for distribution via package managers. 

Tests validate functionality across supported environments. 

We use Jasmine and Karma for unit testing, which helps verify that each component of our software performs as expected. Tests are run against both the development and release builds.

Additionally, we conduct smokescreen tests on the build artifacts to confirm package.json configurations. This lets us catch compatibility issues across various platforms, such as Node.js LTS and web browsers early in the process.

3. Static Analysis and Code Quality Metrics

Static analysis and formatting checks ensure code consistency and quality. 

We use tools like ESLint for JavaScript linting and markdownlint for Markdown files to catch syntactic and stylistic errors before they are merged. Prettier enforces a uniform code format across all contributions. Additionally, we track code coverage by instrumenting the code using istanbul to ensure that tests adequately cover new and existing code, and finally count the lines of source and test code using cloc.

Automatic deployments make the latest builds readily available for testing and review. Each build is uploaded to an S3 bucket, allowing developers to access and review functionality and documentation without needing to build locally. We publish build artifacts, the zip file, and npm package, which simplifies integration testing with other applications such as Cesium ion. 

Keeping security in mind, we need to make sure only authorized sources deploy to AWS, so these deployment steps are restricted based on the author’s commit status.

Looking ahead, we plan to enhance our CI process with several key improvements. We’d like to incorporate end-to-end screenshot tests using Playwright to ensure visual consistency across releases, which developers currently run locally. Additionally, we aim to improve code quality through inline documentation linting, spellcheck, and other static validations to catch errors before they make it to production. We are also exploring the numerous potential integrations with GitHub Actions to further automate our release processes.

We are committed to continuously improving the CesiumJS CI process and value input from the developer community. If you have suggestions or would like to contribute, please start a conversation on GitHub. Your insights can help improve our workflows.

CI for CesiumJS: A Deep Dive into Our GitHub Actions Workflow

Cesium ion Self-Hosted is our solution for geospatial workloads that require isolated environments detached from the public internet or that require an application to be hosted in the cloud behind a user’s own identity provider. Cesium ion Self-Hosted is a Kubernetes based application that provides feature parity with Cesium ion SaaS by leveraging the same code base. The next evolutionary step in our product line, Cesium ion Self-Hosted caters to both small and large enterprises, empowering them with greater control over Cesium’s offerings. In this blog we provide an overview of the architecture behind the Kubernetes application.


As stated in our blog post describing the architecture of Cesium ion SaaS, Cesium ion is an amalgamation of small pieces that each perform a distinct function. Each piece is containerized individually for consistency between development and production. In the AWS deployment of our SaaS product, we use Amazon ECS to orchestrate spinning up, tearing down, and doing other management of the containers. For our self-hosted implementation, we keep the same architecture, but we can’t rely on Amazon services. We also need to integrate Cesium ion Self-Hosted into our users’ diverse environments, cloud providers, and infrastructure.


Kubernetes is a widely used open source container orchestrator that allows for declarative configuration of resources. Container orchestrator in this context means an automated system that spins up, tears down, and regularly checks resources based on the configuration provided. For our use case, Kubernetes acts as a drop-in replacement for AWS and was the obvious choice to use in the self-hosted product. Kubernetes scales across our users’ existing operations and provides them with a platform-agnostic solution.


Since many of our users already have sophisticated Kubernetes clusters set up, they would find it difficult to integrate pre-defined Kubernetes objects from Cesium. We needed some way of allowing users to specify their custom requirements in a configuration file and have our application change its behavior based on those requirements. We decided to leverage Helm, a package manager for Kubernetes, which allows a user’s desired configuration to be supplied to our application through a top level configuration file. This also makes bringing up the entire Self-Hosted application extremely easy since it only requires one command to install. Similarly, updates are also streamlined through Helm as it handles tearing down old deployments and spinning up new ones with just one command. 

This diagram illustrates a high level view of the architecture that gets deployed in a Kubernetes cluster.

Differences between the architectures of Cesium ion SaaS and Self-Hosted

SaaS and Self-Hosted, while providing similar functionality, diverge due to their different deployment environments, necessitating different implementations. For instance, in our SaaS architecture blog we detailed how AWS S3 was perfect for our use case of storing a large amount of small files. But for a Self-Hosted product that is operating in an offline environment, backing up everything on a system like S3 is not possible and using services that imitate S3 can come with substantial financial cost. Below are some examples of differences between the two environments and the solutions we came up with for these deployment modes:

In a Self-Hosted Kubernetes based environment, we need to provide a way for users to write data locally on their volumes mounted to the pods in the cluster. For this reason, we decided to implement a SQLite based solution. Since tiled assets can get extremely large, saving them as a “pile of files” on a file system can become challenging to manage. Instead, we decided to go with SQLite databases, facilitating ease of tiling and management of outputs.

Because these assets are stored in SQLite databases, we have developed a custom asset server written in Node.Js and Restify that handles serving these assets. It also manages authentication and authorization using temporary JWT credentials supplied from the API Server. Self-Hosted customers can expose the asset server with a CDN of their choice for edge caching to provide a similar setup to the one we have on SaaS.

The asset server also serves static assets like CZML, KML, GeoJSON, and glTF and images required by Cesium stories. The asset server is containerized and defined as a Kubernetes Deployment object. It is made to maximize performance by leveraging available CPU cores within its pod and dynamically scale instances based on resource utilization. It performs caching of individual elements stored in its asset databases by using an LRU (Least Recently Used) strategy.
 


For our Self-Hosted offering, the API server leverages the same code as SaaS and performs an additional function: it accepts source asset files through an HTTP multi-part upload. The HTTP multi-part upload functionality replaces uploads done directly to AWS S3 in SaaS. The API server container is used within a Kubernetes deployment that scales the API server’s pods based on resource usage. These pods are exposed through individual ClusterIP services behind a Kubernetes ingress, an API object that exposes routes from outside the cluster to services within the cluster. TLS (Transport Layer Security) can be configured to work with this set up to provide secure HTTPS deployments. 

The API server is backed by a SQL database to store asset and user information. Since the API server works with any SQL based database, users retain the flexibility of selecting their preferred SQL database provider to integrate with the API server. 


In Cesium ion Self-Hosted, we need some way of launching jobs for heterogeneous source data that all require different hardware configurations. This requirement is the same in SaaS, where we use AWS Batch to do this. In Self-Hosted we use Kubernetes Jobs that act as almost a drop in replacement for AWS Batch by providing a similar level of functionality. It allows us to run jobs in isolated containers while placing new jobs in a queue until resources become available.

Since the API server handles source file uploads, the same volume is mounted to the tiling container, which now has access to the source data. The tiling pipeline then processes this data and outputs SQLite files in cases of imagery, terrain, and 3D Tiles workloads. The reason for choosing databases is to allow the assets to be easily manageable by not placing millions of tiny files on a volume. This also makes it easy to ship over 470 million tiles in a single file to our customers as part of our global data offering. 


Cesium ion Self-Hosted defaults to single-user mode, which runs without a built-in authentication system and assumes all site visitors are the same user. To address authentication needs, Self-Hosted users have the option to integrate with their SAML providers, affording administrators control over user access within their organizations. This approach not only ensures ease of integration with enterprise authentication software but also enhances security compared to custom authentication implementations.



The API server, asset server, and front end SPA are all defined as Kubernetes deployments, allowing for horizontal scaling to accommodate high request usage. Each of these pods is exposed through a service sitting behind a Kubernetes ingress, enabling external user access. The tiling pipeline on the other hand runs in individual pods executed through Kubernetes Jobs. Shared volumes for both asset sources and tiled assets are mounted onto the API server and tiling pipeline. This approach simplifies the tiling process by eliminating the need to copy and move assets between volumes. Similarly, the tiled assets volume is also mounted onto the asset server to prevent duplication and optimize asset serving.

Lastly, Cesium ion Self-Hosted includes a PostgreSQL Helm chart provided by Bitnami, allowing users to swiftly set up a database instance, further enhancing deployment ease and efficiency. This instance can be replaced by a user-managed PostgreSQL instance.