# Output Tuning

> Control output size and processing time with zoom levels, threads, and disk configuration.

## Max Zoom Levels

The `--max-zoom` option controls the maximum detail level. Each additional zoom level roughly **quadruples** the number of tiles.

| Max Zoom | Approx. Tile Count (planet) | Typical Output Size | Use Case |
| --- | --- | --- | --- |
| 6 | ~5,000 | ~50 MB | World overview, continental boundaries |
| 8 | ~85,000 | ~500 MB | Country-level detail |
| 10 | ~1.3 million | ~5 GB | Regional roads and land use |
| 12 | ~22 million | ~30 GB | City blocks visible |
| 14 | ~350 million | ~200 GB | Full detail, individual buildings |
| 15 | ~1.4 billion | ~500+ GB | Maximum detail (large output) |

::note
Output sizes are approximate and vary by region density. Urban areas produce more tiles than oceans due to deduplication of empty tiles.
::

### Choosing the Right Zoom Level

- **Zoom 14** is the default and recommended for most use cases. It provides full building-level detail without excessive output size.
- **Zoom 10–12** is a good choice for overview maps or when storage is limited.
- **Zoom 15** should only be used when maximum detail is required and storage is not a concern.

## Disk Space Estimates

Plan for these storage requirements:

| Component | Size Estimate | Notes |
| --- | --- | --- |
| Input data (Overture) | ~200 GB (planet) | Downloaded GeoParquet files |
| Temporary sort files | ~1.5× input size | LZ4 compressed, stored in `--tmpdir` |
| Output PMTiles | ~1× input size | After deduplication (30–50% savings) |
| **Total disk needed** | ~3.5× input size | Input + temp + output |

For a full planet build at zoom 14:

```
Input:  ~200 GB
Temp:   ~300 GB
Output: ~200 GB
─────────────────
Total:  ~700 GB free disk space recommended
```

::warning
Ensure your `--tmpdir` has enough space for temporary files. Running out of disk during the sort phase will cause the build to fail.
::

### Reclaiming Source Data During the Build

By default every Overture Parquet file stays on disk for the whole read, so peak usage is `input + sort chunks`. On a disk-constrained machine that is the difference between a build completing and a build failing with `ENOSPC`.

`--reclaim-source-after-read` unlinks each Parquet file as soon as its features are safely in the sort chunks:

```bash
geolith \
  --data /mnt/data/overture-2026-08-19.0 \
  --output /mnt/data/planet.pmtiles \
  --reclaim-source-after-read
```

| | Peak during the Overture read |
| --- | --- |
| Default | input + sort chunks |
| With `--reclaim-source-after-read` | ~input (source shrinks faster than chunks grow) |

A file is removed only after both its read **and** its chunk flush succeed, so a mid-read failure leaves the remaining sources intact. Only Overture inputs are affected — OSM PBF, Natural Earth, shapefiles, and GeoJSON are never touched.

::warning
Reclaimed files are gone: re-download the release to restore them. Restarting a partial build without `--resume` will need them back.
::

## Thread Count

The `--threads` option controls parallelism for feature processing (Phase 1).

| Threads | Best For |
| --- | --- |
| Default (all cores) | Dedicated build machine, fastest processing |
| Half cores | Shared machine, leaves headroom for other tasks |
| 4–8 | Laptops or machines with limited cooling |

```bash
# Use 8 threads on a 16-core machine
geolith --data ./overture-data --output planet.pmtiles --threads 8
```

::tip
Memory usage scales roughly linearly with thread count due to per-thread buffers. If you're memory-constrained, reducing threads can help.
::

## Temporary Directory

The `--tmpdir` option controls where external sort files are written. This is the most I/O-intensive part of the pipeline.

**Recommendations:**

- Use the fastest available disk (NVMe SSD preferred)
- Avoid network-mounted filesystems (NFS, SMB)
- Avoid the same physical disk as `--data` if possible (reduces I/O contention)
- Ensure 1.5× the input data size is available

```bash
# Use a dedicated fast SSD for temp files
geolith \
  --data /mnt/data/overture \
  --output /mnt/data/planet.pmtiles \
  --tmpdir /mnt/fast-nvme/tmp
```

## Optimal Configuration Summary

For a dedicated planet build on a capable machine:

```bash
geolith \
  --data /mnt/data/overture-2025.01.0 \
  --output /mnt/data/planet.pmtiles \
  --max-zoom 14 \
  --tmpdir /mnt/nvme/tmp \
  --threads $(nproc)
```

| Setting | Value | Why |
| --- | --- | --- |
| `--max-zoom 14` | Full building detail | Good balance of detail and size |
| `--tmpdir` on NVMe | Fastest sort phase | External sort is I/O bound |
| `--threads $(nproc)` | All cores | Maximize parallelism |
| Separate disks for data/tmp/output | Reduced I/O contention | Parallel reads and writes |