tileyolo 0.2.0

A simple raster-based XYZ tile server for serving GeoTIFFs
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120

# TileYolo

**Serve GeoTIFFs as an XYZ tile API with zero configuration.**

Drop your TIFFs into subfolders by style and run `tileyolo` — it handles everything else.

## Install

```bash
cargo install tileyolo
```

Or use as a library:

```bash
cargo add tileyolo
```

## Usage

#### Dependencies

* GDAL

### Cargo

1. `cd` into your data directory (parent of style subfolders).
2. Run:
   ```bash
   tileyolo
   ```
3. Point your XYZ-capable client (browser, QGIS, Leaflet, etc.) at:
   ```text
   http://localhost:8000/tiles/{layer}/{z}/{x}/{y}
   ```
   - **`{layer}`** is the TIFF filename (without extension).

TileYolo will auto-detect styles (`style.txt` or built-in palettes), handle no-data values, and serve tiles on port 8000.

### Docker

To run with the docker image on port 8000 and mapping the local folder `./data`, 
use the command:

```
docker run -v ./data:/app/data -p 8000:8000 tileyolo
```

## Styles & Folder Structure

Organize your GeoTIFFs into style-specific subfolders:

```text
./data/
├── default/
│   ├── layer1.tif
│   ├── layer2.tif
│   └── style.txt    # QGIS-exported colour stops
├── viridis/
│   ├── layer3.tif
│   └── layer4.tif   # uses built-in viridis palette
└── grayscale/
    └── layer5.tif   # no style.txt → linear grayscale
```

- **Custom styles**: Folders with a `style.txt` (QGIS export) use those exact colour stops.
- **Built-in palettes**: Folders named `viridis`, `magma`, `plasma`, `inferno`, `turbo`, `cubehelix_default`, `rainbow`, `spectral`, or `sinebow` apply the corresponding gradient.
- **Grayscale fallback**: Other folders without any style file render in linear grayscale.

## Sample Output

![Startup example with file tree](./docs/startup.svg)

## Configuration

TileYolo has minimal options:

```bash
$ tileyolo --help
Usage: tileyolo [OPTIONS]

Options:
  --data-folder <DIR>  Path to data folder [default: /home/.../data]
  -h, --help           Print help
  -V, --version        Print version
```

## QGIS `style.txt` Example

```text
# QGIS Generated Colour Map Export File
INTERPOLATION:INTERPOLATED
0,215,25,28,255,0
100,253,174,97,255,100
200,255,255,191,255,200
300,171,221,164,255,300
400,43,131,186,255,400
```

See [QGIS Raster Properties → Symbology → Colour Ramp](https://docs.qgis.org/3.40/en/docs/user_manual/working_with_raster/raster_properties.html#id13) for export instructions.

## Why TileYolo?

I needed a zero‑config, lightweight XYZ tile server for GeoTIFFs. TileYolo does just that: drag, drop, and go.

## Roadmap

- Speed up startup with caching
- Tile caching for performance
- S3 ~~and COG~~ support
- ~~Additional built-in palettes~~
- Contributions welcome

## Caveats

- Only **band 1** is served
- Output CRS is **EPSG:3857** (Web Mercator)
- Input TIFFs must define a CRS
- Tested on small to medium rasters; large rasters may require more resources
- Reprojection using [nearest neighbour](https://gdal.org/en/stable/programs/gdalwarp.html#cmdoption-gdalwarp-r)