Voxel Earth

Google Earth 3D Tiles → Voxels

Download Google Earth 3D tiles around any location and convert them to voxel data using pure Node.js. No game engines or external dependencies required beyond Node.js packages.

Features

🌍 Geocoding Support: Convert addresses to coordinates automatically
📦 3D Tile Download: Fetch Google Earth 3D tiles in GLB format
🎮 Voxelization: Convert 3D meshes to colored voxel grids
🎨 Texture Sampling: Extract colors from mesh textures
📊 JSON Output: Export voxel data in a simple JSON format
🖼️ Visualizer: Web-based tool to preview voxel data

Installation

Prerequisites

Node.js (v18 or later recommended for native fetch support)
Google API Key with access to:
- Geocoding API (for address → lat/lng conversion)
- Google Earth 3D Tiles API / Map Tiles API

Setup

Clone this repository:

git clone <repository-url>
cd voxel-earth

Install dependencies:
```
npm install
```
This installs:
- three - 3D library for loading GLB files
- axios - HTTP client for API requests
- sharp - Image processing for texture decoding
- draco3d - Draco mesh compression support
- jpeg-js - JPEG image decoding
- p-queue - Parallel download queue
- yargs - Command-line argument parsing

Usage

Basic Command

node run_pipeline.js --key YOUR_API_KEY --location "Eiffel Tower, Paris" --radius 50 --out ./output

Command-Line Arguments

Argument	Required	Description
--key YOUR_API_KEY \
--location "Golden Gate Bridge" \
--radius 30 \
--out ./test \
--resolution 100

How It Works

The pipeline consists of three main stages:

1. Geocoding (Optional)

If you provide a --location instead of coordinates, the script uses the Google Geocoding API to convert the address into latitude/longitude.

2. Tile Download (`tile_downloader.js`)

Queries the Google Earth 3D Tiles API to get the tileset hierarchy
Performs breadth-first search to find tiles within the specified radius
Downloads GLB files for each intersecting tile
Applies rotation transforms using rotateUtils.cjs to align tiles to a common origin
Saves rotated GLB files to <output>/tiles/

3. Voxelization (`voxelize_tiles.js` + `voxelizer.worker.js`)

Loads each GLB file using Three.js GLTFLoader
Decodes textures from the mesh using sharp and jpeg-js
Performs ray-casting voxelization at the specified resolution
Samples colors from textures for each voxel
Writes voxel data to <output>/voxels/*.json

Output Format

The pipeline creates two subdirectories in your output folder:

output/
├── tiles/          # Rotated GLB files
│   ├── abc123...glb
│   ├── def456...glb
│   └── ...
└── voxels/         # Voxel JSON files
    ├── abc123..._voxels.json
    ├── def456..._voxels.json
    └── ...

Voxel JSON Structure

Each voxel JSON file contains:

{
  "voxels": [
    {
      "x": 0, "y": 5, "z": 10,      // Grid coordinates
      "wx": 4.2, "wy": -1.5, "wz": 0.3,  // World coordinates (meters)
      "r": 142, "g": 128, "b": 105, "a": 255  // RGBA color
    },
    // ... more voxels
  ]
}

Grid coordinates (x, y, z): Integer indices from 0 to resolution-1
World coordinates (wx, wy, wz): Relative positions in meters from the origin tile
Color (r, g, b, a): RGBA values (0-255)

Visualizer

The repository includes a web-based visualizer to preview voxel data:

Open visualizer.html in a web browser
Load a voxel JSON file from the output directory
Interact with the 3D view:
- Left mouse: Rotate
- Right mouse: Pan
- Scroll: Zoom

Getting a Google API Key

Go to the Google Cloud Console
Create a new project (or select an existing one)
Enable the following APIs:
- Geocoding API (for address lookups)
- Map Tiles API (for 3D tile access)
Go to APIs & Services → Credentials
Click Create Credentials → API Key
(Optional) Restrict the key to only the APIs you need

Note: The Google Earth 3D Tiles API may require billing to be enabled on your Google Cloud project, even if you stay within the free tier.

Troubleshooting

"Couldn't load texture blob:nodedata:..."

This warning is normal. It appears because Three.js logs when textures are decoded from binary data. The textures are still processed correctly by sharp and jpeg-js.

"Elevation API error: REQUEST_DENIED"

The Elevation API is not required for the pipeline to work. The script assumes elevation = 0 if it can't fetch it. You can safely ignore this warning.

No tiles downloaded

Check that your API key has access to the Map Tiles API / Google Earth 3D Tiles API
Verify billing is enabled on your Google Cloud project
Try a well-known location like "Eiffel Tower, Paris" to confirm geocoding works
Increase the --radius value (try 100-200 meters)

Out of memory during voxelization

Reduce --resolution (try 100 or 150 instead of 200)
Reduce --radius to download fewer tiles
Close other applications to free up RAM

Pipeline hangs or freezes

Check your internet connection
The tile download step can take several minutes for large areas
Monitor the console output for progress messages

Project Structure

voxel-earth/
├── run_pipeline.js          # Main entry point
├── tile_downloader.js       # Download Google Earth tiles
├── voxelize_tiles.js        # Voxelization orchestrator
├── voxelizer.worker.js      # Voxelization worker logic
├── rotateUtils.cjs          # Tile rotation utilities
├── visualizer.html          # Web-based voxel viewer
├── package.json             # Node.js dependencies
└── README.md                # This file

Advanced Usage

Custom Resolution

Higher resolutions produce denser voxel grids but increase memory usage and processing time:

# Low resolution (faster, less detail)
node run_pipeline.js --key KEY --location "Paris" --radius 50 --out ./out --resolution 50

# High resolution (slower, more detail)
node run_pipeline.js --key KEY --location "Paris" --radius 50 --out ./out --resolution 300

Parallel Downloads

The tile downloader uses 4 parallel workers by default. This is set in run_pipeline.js line 140:

const tileArgs = ['--key', key, '--lat', String(lat), '--lng', String(lng), '--radius', String(radius), '--out', tilesDir, '--parallel', '4'];

You can modify the '4' value to increase/decrease parallelism.

License

ISC

Credits

Three.js: 3D library for WebGL
Sharp: High-performance image processing

FAQ

Q: Can I use this offline?
A: No, the pipeline requires internet access to download tiles from Google's servers.

Q: What coordinate system is used?
A: World coordinates are in ECEF (Earth-Centered, Earth-Fixed) meters, rotated and translated to a local origin based on the first tile.

Q: Can I import the voxels into Minecraft, Minetest, or other games?
A: The JSON output is game-agnostic. You'll need to write a custom importer for your target platform. The repository previously included a Luanti/Minetest mod, but it has been removed to focus on the Node.js pipeline.

Q: How accurate are the voxels?
A: Accuracy depends on the resolution parameter and the quality of Google's 3D tiles. Higher resolutions produce more detailed voxels but take longer to process.

Q: Why are there warnings about textures?
A: Three.js logs warnings when loading textures from binary data. These can be safely ignored - the textures are still processed correctly.

⚠️ Important Notice & Terms of Service

This tool is intended for educational and debugging purposes only.

Google 3D Tiles Usage Restrictions

If you are using Google Earth 3D Tiles, please be aware of the following restrictions from Google's Terms of Service:

No Downloading or Storing: You are not permitted to download, cache, or store Google 3D Tiles data beyond temporary caching for real-time visualization purposes.
Visualization Only: Google 3D Tiles may only be used for real-time visualization within applications. Permanent storage, offline use, or redistribution of tile data is prohibited.
Attribution Required: You must display appropriate Google attribution when using their tiles.

By using this tool with Google's 3D Tiles API, you accept full responsibility for complying with Google's Terms of Service and the Maps Platform Acceptable Use Policy.

Other 3D Tile Sources

If you are using 3D Tiles from other providers (Cesium Ion, custom tilesets, etc.), please ensure you review and comply with their respective Terms of Service and licensing agreements.

The authors of this tool are not responsible for any misuse or Terms of Service violations.

Contributing

Contributions are welcome! Please open an issue or pull request on GitHub.

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
.gitattributes		.gitattributes
.gitignore		.gitignore
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
rotateUtils.cjs		rotateUtils.cjs
run_pipeline.js		run_pipeline.js
tile_downloader.js		tile_downloader.js
visualizer.html		visualizer.html
voxelize_tiles.js		voxelize_tiles.js
voxelizer.worker.js		voxelizer.worker.js

voxelearth/nodejs-voxelearth

Folders and files

Latest commit

History

Repository files navigation