Converted tilesets faithfully match the level of detail and precision of the source CDB, with support for most common CDB layers and their associated feature attributes. See [Features](#clipboard-Features) for a full list of supported datasets and [Performance](#checkered_flag-Performance) for performance comparisons.
3D Tiles is designed for efficient runtime visualization and analytics. The pipeline preserves feature attributes from CDB, enabling runtime querying, styling, and analytics to gain deeper insights into the data.
_View of downtown San Diego with terrain, imagery, clamped building models, instanced trees, and Coronado Bridge in the distance, loaded as 3D Tiles in [CesiumJS](https://cesium.com/cesiumjs/). See the live demo [here](https://sandcastle.cesium.com/standalone.html#c=xZZtU+M2EID/iiafkpkgW5bjFy7HFBLgnCGhR8LBUfeDsRUiYsupJIcLHf57ZTuvJLzcdUq/WLZWu/vsrrSWpoFTHjAJWkTQLOn0QRCGRAggUzBLMw5oykAgBJHCZ+Ua6KUMRmQYZLE8LBYP0jFh4DPwK2TWGd2ehvScdrzLRw/1qCc8dtEIW57ljSfX31odF6pFf0WnY7XIe+wlJ6Pu403S7SPavR/PzgZfzW67K8+vjh/PW2h8k5zcd6++/7hJLme9K4+etTqTG2Ws1/4qvCQeReq9O/j+0Bscou7gsNHDOozs66R3e+Ilvx/jowa961x3Lu0bpx0c6fbkSNxf3I7RFykH7WzsVz75zGfTgIMpJQ+EqygYeZhnA34r5qp+JSy+WymTAWWE+5XaUu84JtNA5mnaUC0H3B7QmKjsVf/2GQAZj/fBKosXRKgUhwQOeZoc5kn2oipyrIar1+o+e8qdlFhQhIQROOE0oZJOiYBBFFWXrlc0p/1uGpFYKJjXNHOYt2Dfi2tjx8xxAXiq+ewt5gXgGvKgnDniNLojHwiODetnwDcwt/EHnBDxsfSNn6cvKFfwX2YRT+94MBnNekQ+pHz8sRHg90ewjboK4yINov+FX//3/MOMhUX7EKP0AbfLMlXzjxoocJanHOaTKr58+JRLFmdpW7CxV18UF5vhmfRpi2kbfJ1uW/qmwbVqrVtam95loh+wKAyEjEmezkGaxrcB7xKWFTX9oyzcvH4ASPJD7qsfUj83tMxgfZmyOlDmlonwK/WFYsoEiUmolJfM1drKLtgsk+RZ0QrWhTvyNQxisbVuPQ3PFjzNcRbj7rByA2Bu4Zcj2In2KyFspuJ9Eaz5+c8D2FWq10ow58+HP/3FH7Y832GQEB7AYTwbpGXLiIiQlJXXgP2NBhNwqd4Chqt7htkwXAtByzIwMk1Tt+pgz7RtFyEEsWWaLrYbZh1g01AjgrZhGhZysWOVXSbllKgLyNzJMh8R5SR81bMOTd1FDWTqCLsmcg1dedlTs8hsOJaFsIltpJ6NYtZBhmMaucAybdd0asvCZJOXg9Oh4ejYMmwLWw11J7BQ6cPVTcdUhrBtG4ZjOXWgQ2zo2HFtrDsOxtiYeyi3SpTxRYR4fgXy2c4z99ZGfbHAlXqlKeQsJge5w99oMkm5zHt+FUJNkmQSByos7TYLx0TCUBT/y6a2UGlGdApo9HnHrRCEsborK8kwi+M+fSR+5aCpqfUbarGCouzufEp4HKiNX2A0R+jgrBRACJua+sydPteVZd9bs6uiGUk5EfuaJlYtskSDYZpod0EcEz7T/gE)_.
#
### :rocket: Getting Started
See [Getting Started](#getting-started) for installation, build, and usage instructions.
### :green_book: License
[Apache 2.0](http://www.apache.org/licenses/LICENSE-2.0.html). CDB to 3D Tiles is free for both commercial and non-commercial use. See [LICENSE.md](./LICENSE.md) for more details.
The [San Diego CDB](https://gsa-temp-public.s3.us-east-1.amazonaws.com/CDB_san_diego_v4.1.zip) end-user license agreement can be found [here](./Doc/SanDiego_CDB_EULA.pdf).
### :heavy_plus_sign: Contributions
Pull requests are appreciated. Please use the same [Contributor License Agreement (CLA)](https://github.com/CesiumGS/cesium/blob/master/CONTRIBUTING.md) used for [CesiumJS](https://cesium.com/cesiumjs/).
### :clipboard: Features
The following CDB features are supported:
#### Feature checklist
Dataset|CDB Name|Supported
--|--|--
Primary Elevation|`001_Elevation`|:heavy_check_mark:
Primary Imagery|`004_Imagery`|:heavy_check_mark:
Road Network|`201_RoadNetwork`|:heavy_check_mark:
Rail Road Network|`202_RailRoadNetwork`|:heavy_check_mark:
Power Line Network|`203_PowerLineNetwork`|:heavy_check_mark:
Hydrography Network|`204_HydrographyNetwork`|:heavy_check_mark:
Geotypical models|`101_GTFeature`, `500_GTModelGeometry`, `501_GTModelTexture`|:heavy_check_mark:
Geospecific models|`100_GSFeature`, `300_GSModelGeometry`, `301_GSModelTexture`|:heavy_check_mark:
Raster Materials|`005_RMTexture`, `006_RMDescriptor`|:heavy_check_mark:
Moving models|`600_MModelGeometry`, `601_GSModelTexture`|:x:
Min Max Elevation|`002_MinMaxElevation` `003_MaxCulture`|:x:
Geopolitical Boundaries|`102_GeoPolitical`|:x:
Vector Materials|`200_VectorMaterial`|:x:
Navigation|`400_NavData`, `401_Navigation`|:x:
Bathymetry||:x:
Seasonal Imagery||:x:
#### Additional capabilities
Capability|Supported
--|--
Preserve instance and class attributes for models and vector layers|:heavy_check_mark:
Preserve geometry and texture quality with command line options for controlling mesh decimation|:heavy_check_mark:
Clamp models to the primary elevation dataset|:heavy_check_mark:
Clamp vector layers to the primary elevation dataset|:x:
#### Roadmap
* Windows support
* Performance improvements
* Automatic upload to Cesium ion
* Support more CDB datasets
* Clamp vector layers
If you would like to provide feedback or accelerate the product roadmap for features you would like to see included, please contact [Shehzan Mohammed](mailto:shehzan@cesium.com).
#### CDB versions
All versions of CDB are supported. CDB 3.0 and CDB OGC 1.2 (draft) have been tested most during development.
### :checkered_flag: Performance
Performance numbers for [San Diego CDB](https://gsa-temp-public.s3.us-east-1.amazonaws.com/CDB_san_diego_v4.1.zip) measured on a Dell XPS 15 7590
Dataset|Time Elapsed|CDB Size|3D Tiles Size
--|--|--|--
Elevation and Imagery | 38 minutes | 20.3 GB | 17.1 GB
Road Network | 2 seconds | 166.8 MB | 121.3 MB
Hydrography Network | 0.2 seconds | 605 kB | 533.4 kB
GTModel | 0.8 seconds | 221.2 MB | 3.2 MB
GSModel | 9 minutes | 7.6 GB | 1.8 GB
**Total** | **47 minutes** | **28.3 GB** | **19.0 GB**
## Getting Started
### Prerequisites
- Linux (Windows support coming soon)
- C++ compiler that supports C++17 (tested on GCC 9.3.0)
- CMake version 3.15 or higher
- GDAL version 3.0.4 or higher
- OpenGL (needed by OpenSceneGraph)
To install GDAL 3.0.4 on Debian-based systems:
```bash
sudo add-apt-repository ppa:ubuntugis/ppa && sudo apt-get update
sudo apt-get update
sudo apt-get install libgdal-dev
```
To install OpenGL on Debian-based headless systems:
```bash
sudo apt-get install libgl1-mesa-dev
```
### Installing
Clone the repo with:
```
git clone --recurse-submodules git@github.com:CesiumGS/cdb-to-3dtiles.git
```
If `--recurse-submodules` is omitted, run the following command to update submodules:
```
git submodule update --init --recursive
```
### Building
The converter can be built on the command-line with CMake (given that you satisfy all [prerequisites](#prerequisites)):
```
cmake -B Build -S .
cmake --build Build --config Release -j 4
```
The executable can be found in the directory `Build/CLI/CDBConverter`
### Usage
```
Usage:
CDBConverter [OPTION...]
-i, --input arg CDB directory
-o, --output arg 3D Tiles output directory
--combine arg Combine converted datasets into one tileset.
Each dataset format is
{DatasetName}_{ComponentSelector1}_{ComponentSelector2}. Repeat this
option to group different dataset into
different tilesets.E.g:
--combine=Elevation_1_1,GSModels_1_1 --combine=GTModels_2_1,GTModels_1_1
will combine Elevation_1_1 and GSModels_1_1 into
one tileset. GTModels_2_1 and GTModels_1_1
will be combined into a different tileset
(default: Elevation_1_1,GSModels_1_1,GTModels_2_1,GTModels_1_1)
--elevation-normal Generate elevation normal
--elevation-lod Generate elevation and imagery based on
elevation LOD only
--elevation-decimate-error arg
Set target error when decimating elevation
mesh. Target error is normalized to 0..1 (0.01
means the simplifier maintains the error to be
below 1% of the mesh extents) (default: 0.01)
--elevation-threshold-indices arg
Set target percent of indices when decimating
elevation mesh (default: 0.3)
--3d-tiles-next Generate 3D Tiles Next
-h, --help Print usage
```
### Example
The following command converts [San Diego CDB](https://gsa-temp-public.s3.us-east-1.amazonaws.com/CDB_san_diego_v4.1.zip) to 3D Tiles:
```
./Build/CLI/CDBConverter -i CDB_san_diego_v4.1 -o San_Diego
```
### Unit Tests
To run unit tests, run the following command:
```
./Build/Tests/Tests
```
### Docker
You can use Docker to simplify setting up the environment for building and testing. You must install [Docker Engine CE For Ubuntu](https://docs.docker.com/install/linux/docker-ce/ubuntu/) to do so.
The converter can be built with:
```bash
./Docker/build-container.sh
./Docker/build-cdb-to-3dtiles.sh
```
The executable can be found in the directory `Build/CLI/CDBConverter`
Run units tests with the following command:
```
./Docker/run-tests.sh
```
### 3D Tiles Structure
The converter generates multiple 3D Tilesets from the input CDB:
- Primary Elevation and Primary Imagery are combined into a single tileset
- Geotypical models are combined into a single tileset
- Geospecific models are combined into a single tileset
- Vector datasets are written as separate tilesets:
- Road Network
- Rail Road Network
- Power Line Network
- Hydrography Network
The generated tilesets will be placed in a GeoCell directory similar to how the CDB is organized. For example, the generated tilesets for San Diego will be placed in the `San_Diego/Tiles/N32/W118` directory.
A CDB tile can store different geometries depending on its component selectors. For example, a Hydrography Network tile can have lineal and polygon features within the same tile, which are differentiated by their second respective component selector in the file name. For this reason, a `tileset.json` will be placed in the directory name that make up of the two component selectors, `{Component Selector 1}_{Component Selector 2}`. For example:
- The lineal tileset of the Hydrography Network dataset will be placed in `HydrographyNetwork/2_3` directory
- The polygon tileset of the Hydrography Network dataset will be placed in `HydrographyNetwork/2_5` directory
Below is the output directory of the converted San Diego 3D Tiles:
[Live Demo of raster materials](http://cesium-dev.s3-website-us-east-1.amazonaws.com/cesium/feature-id-texture-mvp/Apps/Sandcastle/standalone.html#c=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)
## Releases
We release as often as needed. CDB To 3D Tiles strictly follows [semver](https://semver.org/).
- Update the project version number in [CMakeLists.txt](./CMakeLists.txt)
- Proofread [CHANGES.md](./CHANGES.md) and make any required updates
- Make sure all unit tests pass
- Commit and push the above changes to `master`
- Create a git tag for the version and push it:
- `git tag -a 0.1.0 -m "0.1.0 release"`
- `git push origin 0.1.0`
## Featured Demo
[Live Demo](https://sandcastle.cesium.com/standalone.html#c=xZZtU+M2EID/iiafkpkgW5bjFy7HFBLgnCGhR8LBUfeDsRUiYsupJIcLHf57ZTuvJLzcdUq/WLZWu/vsrrSWpoFTHjAJWkTQLOn0QRCGRAggUzBLMw5oykAgBJHCZ+Ua6KUMRmQYZLE8LBYP0jFh4DPwK2TWGd2ehvScdrzLRw/1qCc8dtEIW57ljSfX31odF6pFf0WnY7XIe+wlJ6Pu403S7SPavR/PzgZfzW67K8+vjh/PW2h8k5zcd6++/7hJLme9K4+etTqTG2Ws1/4qvCQeReq9O/j+0Bscou7gsNHDOozs66R3e+Ilvx/jowa961x3Lu0bpx0c6fbkSNxf3I7RFykH7WzsVz75zGfTgIMpJQ+EqygYeZhnA34r5qp+JSy+WymTAWWE+5XaUu84JtNA5mnaUC0H3B7QmKjsVf/2GQAZj/fBKosXRKgUhwQOeZoc5kn2oipyrIar1+o+e8qdlFhQhIQROOE0oZJOiYBBFFWXrlc0p/1uGpFYKJjXNHOYt2Dfi2tjx8xxAXiq+ewt5gXgGvKgnDniNLojHwiODetnwDcwt/EHnBDxsfSNn6cvKFfwX2YRT+94MBnNekQ+pHz8sRHg90ewjboK4yINov+FX//3/MOMhUX7EKP0AbfLMlXzjxoocJanHOaTKr58+JRLFmdpW7CxV18UF5vhmfRpi2kbfJ1uW/qmwbVqrVtam95loh+wKAyEjEmezkGaxrcB7xKWFTX9oyzcvH4ASPJD7qsfUj83tMxgfZmyOlDmlonwK/WFYsoEiUmolJfM1drKLtgsk+RZ0QrWhTvyNQxisbVuPQ3PFjzNcRbj7rByA2Bu4Zcj2In2KyFspuJ9Eaz5+c8D2FWq10ow58+HP/3FH7Y832GQEB7AYTwbpGXLiIiQlJXXgP2NBhNwqd4Chqt7htkwXAtByzIwMk1Tt+pgz7RtFyEEsWWaLrYbZh1g01AjgrZhGhZysWOVXSbllKgLyNzJMh8R5SR81bMOTd1FDWTqCLsmcg1dedlTs8hsOJaFsIltpJ6NYtZBhmMaucAybdd0asvCZJOXg9Oh4ejYMmwLWw11J7BQ6cPVTcdUhrBtG4ZjOXWgQ2zo2HFtrDsOxtiYeyi3SpTxRYR4fgXy2c4z99ZGfbHAlXqlKeQsJge5w99oMkm5zHt+FUJNkmQSByos7TYLx0TCUBT/y6a2UGlGdApo9HnHrRCEsborK8kwi+M+fSR+5aCpqfUbarGCouzufEp4HKiNX2A0R+jgrBRACJua+sydPteVZd9bs6uiGUk5EfuaJlYtskSDYZpod0EcEz7T/gE) of San Diego terrain, imagery, and models. Click individual models or vector features to see their metadata.
