OxiGDAL Tile Server

WMS/WMTS tile server for serving geospatial raster data over HTTP, powered by OxiGDAL.

Features

• WMS 1.3.0: Full Web Map Service support

  • GetCapabilities
  • GetMap
  • GetFeatureInfo

• WMTS 1.0.0: Web Map Tile Service

  • GetCapabilities
  • GetTile (KVP and RESTful)
  • Multiple tile matrix sets (Web Mercator, WGS84)

• XYZ Tiles: Simple tile serving

  • Compatible with Leaflet, MapLibre, OpenLayers
  • TileJSON support

• High Performance

  • Async/await with Tokio
  • Multi-level caching (memory + disk)
  • LRU cache eviction
  • Configurable tile sizes

• Pure Rust

  • No C/C++ dependencies
  • Memory safe
  • Fast compilation

Installation

From Source

cd crates/oxigdal-server
cargo build --release

Using Cargo

cargo install --path crates/oxigdal-server

Quick Start

1. Generate a Configuration File

oxigdal-server --generate-config config.toml

2. Edit the Configuration

Edit config.toml to add your datasets:

[[layers]]
name = "landsat"
path = "/path/to/landsat.tif"
formats = ["png", "jpeg"]
tile_size = 256

3. Start the Server

oxigdal-server --config config.toml

The server will start on http://0.0.0.0:8080 by default.

Configuration

Server Settings

[server]
host = "0.0.0.0"      # Bind address
port = 8080            # Bind port
workers = 4            # Number of worker threads (0 = auto)
enable_cors = true     # Enable CORS

Cache Settings

[cache]
memory_size_mb = 256           # In-memory cache size
disk_cache = "/tmp/cache"      # Optional disk cache
ttl_seconds = 3600             # Cache TTL

Layer Configuration

[[layers]]
name = "my-layer"              # Layer identifier
title = "My Layer"             # Display name
path = "/data/layer.tif"       # Path to GeoTIFF
formats = ["png", "jpeg"]      # Supported formats
tile_size = 256                # Tile size in pixels
min_zoom = 0                   # Minimum zoom level
max_zoom = 18                  # Maximum zoom level

API Endpoints

WMS

GET /wms?SERVICE=WMS&REQUEST=GetCapabilities
GET /wms?SERVICE=WMS&REQUEST=GetMap&LAYERS=landsat&BBOX=-180,-90,180,90&WIDTH=512&HEIGHT=512&FORMAT=image/png
GET /wms?SERVICE=WMS&REQUEST=GetFeatureInfo&...

WMTS

GET /wmts?SERVICE=WMTS&REQUEST=GetCapabilities
GET /wmts/1.0.0/{layer}/{tileMatrixSet}/{z}/{x}/{y}.png

XYZ Tiles

GET /tiles/{layer}/{z}/{x}/{y}.png
GET /tiles/{layer}/tilejson

Utility Endpoints

GET /              # Landing page
GET /health        # Health check
GET /stats         # Cache statistics

Usage Examples

Leaflet

const map = L.map('map').setView([0, 0], 2);

L.tileLayer('http://localhost:8080/tiles/landsat/{z}/{x}/{y}.png', {
    attribution: 'OxiGDAL Tile Server',
    maxZoom: 18
}).addTo(map);

MapLibre GL JS

const map = new maplibregl.Map({
    container: 'map',
    style: {
        version: 8,
        sources: {
            'landsat': {
                type: 'raster',
                tiles: ['http://localhost:8080/tiles/landsat/{z}/{x}/{y}.png'],
                tileSize: 256
            }
        },
        layers: [{
            id: 'landsat',
            type: 'raster',
            source: 'landsat'
        }]
    }
});

QGIS

1. Add WMS/WMTS connection
2. URL: http://localhost:8080/wms or http://localhost:8080/wmts
3. Select layers to display

Command-Line Options

oxigdal-server [OPTIONS]

Options:
  -c, --config <FILE>              Configuration file path
      --host <HOST>                Host address (env: OXIGDAL_HOST)
  -p, --port <PORT>                Port number (env: OXIGDAL_PORT)
  -w, --workers <WORKERS>          Number of workers (env: OXIGDAL_WORKERS)
      --log-level <LEVEL>          Log level [default: info]
      --generate-config <FILE>     Generate default config file
  -h, --help                       Print help
  -V, --version                    Print version

Environment Variables

• OXIGDAL_HOST: Server host address
• OXIGDAL_PORT: Server port
• OXIGDAL_WORKERS: Number of worker threads
• OXIGDAL_LOG_LEVEL: Log level (trace, debug, info, warn, error)

Docker

Build

docker build -t oxigdal-server .

Run

docker run -d \
  -p 8080:8080 \
  -v /path/to/data:/data:ro \
  -v /path/to/config.toml:/etc/oxigdal/config.toml:ro \
  oxigdal-server

Performance Tuning

Cache Size

Increase memory cache for better performance:

[cache]
memory_size_mb = 1024  # 1 GB

Workers

Set workers based on your CPU:

[server]
workers = 8  # Or use 0 for auto-detection

Disk Cache

Enable disk cache for persistence:

[cache]
disk_cache = "/var/cache/oxigdal"

Monitoring

Cache Statistics

curl http://localhost:8080/stats

Returns cache hit/miss rates and memory usage.

Health Check

curl http://localhost:8080/health

Returns server status.

Troubleshooting

Server won't start

1. Check configuration file syntax
2. Verify dataset paths exist
3. Ensure port is not in use
4. Check log output with --log-level debug

Tiles not rendering

1. Verify layer is enabled in config
2. Check dataset format is supported
3. Verify tile coordinates are valid
4. Check server logs for errors

Performance issues

1. Increase cache size
2. Enable disk caching
3. Adjust worker count
4. Use appropriate tile sizes

Development

Building

cargo build

Testing

cargo test

Running locally

cargo run -- --config examples/config.toml

License

Apache-2.0

Contributing

Contributions are welcome! Please see the main OxiGDAL repository.

Authors

COOLJAPAN OU (Team Kitasan)