What is the lightest possible method of using Cesium?

Question

I'm interested in using Cesium to build a 3D Earth with custom tiles, but as per the "get started" instructions here, it seems as though you have to download a massive 30mb directory and include the whole thing in your project to have it run correctly. Is this true? Can I not just include Cesium.js and get running like that? I don't need 80% of the UI elements they include anyways.

At the end of the "get started" tutorial, they seem to indicate that all you need to get running are these bits:

<script src="Cesium/Cesium.js"></script>

@import url(Cesium/Widgets/widgets.css);

<div id="cesiumContainer"></div>

var viewer = new Cesium.CesiumViewer('cesiumContainer');

But when I set these bits up, I get this error: "define is not defined" and "Cesium is not defined".

What is the lightest possible way to run Cesium?

Answer 1

That tutorial definitely needs an update and I'll make a note to clean it up. (For starters, there's a bug at the bottom of it, because Cesium.CesiumViewer should just be Cesium.Viewer.) That being said, here's the low-down on what's included in the zip and what you'll want/need for actual development.

• Apps -> Sample applications.
• Source -> AMD modules for module-based development (requirejs, browserify, etc..) also used by the sample applications.
• Specs -> Unit tests.
• ThirdParty -> Third party libraries required for the above.
• Build/Apps -> Built and minified versions of the sampled applications.
• Build/Documentation -> The reference documentation.

This leaves two directories, Build/Cesium and Build/CesiumUnminified, which I'll talk about in a minute.

But first, the technically correct answer to your question is to create the lightest possible Cesium-based application, use the AMD modules we provide. This means you only need to include the Source folder at development time, and then your build process will create the minified and concatenated version of your app for deployment. Using modules ensure you only include the Cesium features you are using. This is different than the "traditional" web development practice of including minified versions of all of your code and libraries in the correct order via script tags at the bottom of your page. Modules are gaining momentum on a daily basis and ES6 along with build systems like Babel are slowly taking over the web dev landscape. We use requirejs ourselves, but there are tons of options out there.

An example of an application built this way is the Cesium Viewer example in Build\Apps\CesiumViewer (source is in Apps\CesiumViewer). The entire built app (uncompressed) is 8.77 megs and exposes pretty much every Cesium feature and capability. 3.65 megs of that is the Natural Earth imagery that ships by default and other data files that the app only pulles down on demand if you use a feature that triggers it. The remaining JavaScript is greatly reduced in size by gzipping compression on the server end. To see this for yourself, run the latest Cesium Viewer link and open the network tab in your browser dev tools. The entire app only sucks down 2.2 megs (and that includes the initial imagery being loaded from Bing. The Cesium portion is only about 426kb. It might suck down a few extra kb if you start loading GeoJSON or KML files, but not much.

Since a module based approach requires additional set up and is still not that common in web development overall, we also supply the Build/Cesium and Build/CesiumUnminified folders. These included fully minified and concatenated versions of Cesium that suck all of the modules into a single file. However, you need more than just the Cesium.js file for deployment. Here's a break down of these folders:

• Build/Assets -> The default imagery/assets that ship with Cesium (imagery/icons/stars/data for ICRF transformations). This data is pulled down as needed depending on how you configure your Cesium application. It's 3.65 megs, but chanes are your app will only ever touch a few kb of that (depending on the features you use). Rather than try and determine what to deploy to the server, I suggest deploying the entire directory (but as I said, the client may never retrieve most of it).
• Build/Workers and Build/ThirdParty -> These contained the concatenated web workers used by Cesium. This includes code used by imagery/terrain, geometry tessellation, and zip file handling. It's pulled down on demand and even if you did something to require all of it, is still under a meg gzipped. These files can't be included in the primary Cesium.js because of the nature of WebWorkers (In our opinion this is a difficiency in the spec).
• Build/Widgets -> contains the concatenated CSS, both in inidividual widget form and in a combined widgets.css file. I recommend just including widgets.css and be done with it (4kb gzipped); but if you are really concerned about size you can bring down individual css files. This folder also contains icons used by the various widgets. Once again, they are only retrieved from the server if needed.

As their names suggestions, Both Build/Cesium and Build/CesiumUnminified are pretty much the same thing. The main difference is that Build/Cesium has been minified and is much smaller. It is also faster because it has a lot of debug code removed in order to improve performance. Our official recommendation is to develop against CesiumUnminified and deploy using Cesium. This will make it easier to develop because you'll get better error handling and callstacks if there are problems in your code.

An example of an application built this way is the Hello World application link. There's actually not much size difference from the built Cesium Viewer app I linked above, but that's because they are essentially the same application built two different ways.

So this answer ended up being a lot longer than I wanted it to be, but Web Development is varied and Cesium tries to do its best to support all of its different approaches. Cesium itself is also incredibly ambitious so we've had to overcome a lot of hurdles that other projects never encounter. Is there room for improvement, absolutely, but we go out of our way to ensure that Cesium is as light as it can be while delivering the features that it has. I think in a 2.0 version we will probably take this even further and try and make things more modular.

I hope that answers your questions and concerns.