Skip to content

Latest commit

 

History

History
248 lines (179 loc) · 12.4 KB

README.md

File metadata and controls

248 lines (179 loc) · 12.4 KB
Raw

CDB to 3D Tiles

Convert Open Geospatial Consortium (OGC) CDB datasets to 3D Tiles OGC Community Standard for efficient streaming and rendering across multiple platforms and devices.

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 for a full list of supported datasets and 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. See the live demo here.

🚀 Getting Started

See Getting Started for installation, build, and usage instructions.

📗 License

Apache 2.0. CDB to 3D Tiles is free for both commercial and non-commercial use. See LICENSE.md for more details.

The San Diego CDB end-user license agreement can be found here.

✨ Contributions

Pull requests are appreciated. Please use the same Contributor License Agreement (CLA) used for CesiumJS.

📋 Features

The following CDB features are supported:

Feature checklist

Dataset CDB Name Supported
Primary Elevation 001_Elevation ✔️
Primary Imagery 004_Imagery ✔️
Road Network 201_RoadNetwork ✔️
Rail Road Network 202_RailRoadNetwork ✔️
Power Line Network 203_PowerLineNetwork ✔️
Hydrography Network 204_HydrographyNetwork ✔️
Geotypical models 101_GTFeature, 500_GTModelGeometry, 501_GTModelTexture ✔️
Geospecific models 100_GSFeature, 300_GSModelGeometry, 301_GSModelTexture ✔️
Moving models 600_MModelGeometry, 601_GSModelTexture ❌
Min Max Elevation 002_MinMaxElevation 003_MaxCulture ❌
Geopolitical Boundaries 102_GeoPolitical ❌
Vector Materials 200_VectorMaterial ❌
Raster Materials 005_RMTexture, 006_RMDescriptor ❌
Navigation 400_NavData, 401_Navigation ❌
Bathymetry ❌
Seasonal Imagery ❌

Additional capabilities

Capability Supported
Preserve instance and class attributes for models and vector layers ✔️
Preserve geometry and texture quality with command line options for controlling mesh decimation ✔️
Clamp models to the primary elevation dataset ✔️
Clamp vector layers to the primary elevation dataset ❌

Roadmap

  • Windows support
  • Performance improvements
  • Automatic upload to Cesium ion
  • Support more CDB datasets
  • Clamp vector layers
  • Output 3D Tiles Next (for interoperability with One World Terrain Well-Formed Format)

If you would like to provide feedback or accelerate the product roadmap for features you would like to see included, please contact Shehzan Mohammed.

CDB versions

All versions of CDB are supported. CDB 3.0 and CDB OGC 1.2 (draft) have been tested most during development.

🏁 Performance

Performance numbers for San Diego CDB 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:

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:

sudo apt-get install libgl1-mesa-dev

Installing

Clone the repo with:

git clone --recurse-submodules [email protected]: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):

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)
  -h, --help                    Print usage

Example

The following command converts San Diego CDB 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 to do so.

The converter can be built with:

./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:

 

Releases

We release as often as needed. CDB To 3D Tiles strictly follows semver.

  • Update the project version number in CMakeLists.txt
  • Proofread CHANGES.md and make any required updates
  • Make sure all unit tests pass
  • Commit and push the above changes to main
  • 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 of San Diego terrain, imagery, and models. Click individual models or vector features to see their metadata.