### Get Help for Tilemaker

Source: https://github.com/systemed/tilemaker/blob/master/docs/RUNNING.md

Displays all available command-line options for the tilemaker tool. This is useful for understanding the full range of functionalities and parameters.

```bash
tilemaker --help
```

--------------------------------

### Tilemaker JSON Configuration Example

Source: https://github.com/systemed/tilemaker/blob/master/docs/CONFIGURATION.md

Defines layers, their zoom level ranges, and global settings for vector tile generation. This JSON file specifies which OpenStreetMap features go into which layers and sets parameters like min/max zoom, compression, and metadata.

```json
{
  "layers": {
    "roads": { "minzoom": 12, "maxzoom": 14 },
    "buildings": { "minzoom": 14, "maxzoom": 14 },
    "pois": { "minzoom": 13, "maxzoom": 14 }
  },
  "settings": {
    "minzoom": 12,
    "maxzoom": 14,
    "basezoom": 14,
    "include_ids": false,
    "compress": "gzip",
    "name": "Tilemaker example",
    "version": "0.1",
    "description": "Sample vector tiles for tilemaker"
  }
}
```

--------------------------------

### Installation Rules (CMake)

Source: https://github.com/systemed/tilemaker/blob/master/CMakeLists.txt

Defines installation rules for the 'tilemaker' project. It installs the man page to 'share/man/man1' and the 'tilemaker' and 'tilemaker-server' executables to the 'bin' directory.

```cmake
install(FILES docs/man/tilemaker.1 DESTINATION share/man/man1)

add_executable(tilemaker-server server/server.cpp)
target_include_directories(tilemaker-server PRIVATE include)
target_link_libraries(tilemaker-server ${THREAD_LIB} ${CMAKE_DL_LIBS} SQLite::SQLite3 Boost::filesystem Boost::program_options)

install(TARGETS tilemaker tilemaker-server RUNTIME DESTINATION bin)
```

--------------------------------

### Basic CSS for Map Container

Source: https://github.com/systemed/tilemaker/blob/master/server/static/index.html

This CSS sets up the basic styling for the map container, ensuring it takes up the full viewport and has no margin or padding.

```css
body { margin:0; padding:0; }
#map { position:absolute; top:0; bottom:0; width:100%; }
```

--------------------------------

### Install tilemaker (Compilation)

Source: https://github.com/systemed/tilemaker/blob/master/README.md

These commands compile and install tilemaker from source after its dependencies are met. 'make' builds the executable, and 'sudo make install' places it in the system's PATH.

```bash
make
sudo make install
```

--------------------------------

### Tilemaker GitHub Action Configuration

Source: https://github.com/systemed/tilemaker/blob/master/docs/RUNNING.md

Example YAML configuration for integrating tilemaker into a GitHub Workflow. This action allows specifying input, output, configuration, process files, and extra arguments.

```yaml
- uses: systemed/tilemaker@v2.0.0
  with:
    # Required, same to --input
    input: /path/to/osm.pbf
    # Required, same to --output. Could be a directory or a .mbtiles files
    output: /path/to/output
    # Optional, same to --config
    # If not being set, default to resources/config-openmaptiles.json
    config: /path/to/config
    # Optional, same to --process
    # If not being set, default to resources/process-openmaptiles.lua
    process: /path/to/lua
    # Optional, other arguments
    # If not being set, default to '--verbose'
    extra: --threads 0
```

--------------------------------

### Serve Vector Tiles with Demonstration Server

Source: https://github.com/systemed/tilemaker/blob/master/README.md

This command starts a local demonstration server to serve generated .mbtiles vector tiles. After running, the tiles can be accessed via a web browser at http://localhost:8080.

```bash
cd server
tilemaker-server /path/to/your/output.mbtiles
```

--------------------------------

### Get Data from Lua Key/Value Store

Source: https://github.com/systemed/tilemaker/blob/master/docs/CONFIGURATION.md

Illustrates how to retrieve a value from Tilemaker's Lua key/value store using a specified key. This is commonly done within `way_function` or similar processing functions. If the key is not found, an empty string is returned.

```lua
function way_function(way)
  local name = GetData("name")
  if name ~= "" then
    -- Use the retrieved name
    print("Processing way for: " .. name)
  end

  local external_data = GetData("external_data")
  if external_data ~= "" then
    -- Process external_data
  end
end
```

--------------------------------

### Run Tilemaker Development Server

Source: https://context7.com/systemed/tilemaker/llms.txt

Commands to start the Tilemaker development server for viewing generated MBTiles. Options include specifying the MBTiles file, a directory for static map viewer files, and a custom port. Docker usage is also demonstrated.

```bash
# Start server with default settings
tilemaker-server /path/to/your/output.mbtiles

# Specify static files directory for map viewer
tilemaker-server /path/to/your/output.mbtiles --static server/static

# Server runs on http://localhost:8080/ by default

# Custom port (if supported)
tilemaker-server /path/to/your/output.mbtiles --port 3000

# Docker server usage
docker run -it --rm -p 8080:8080 -v $(pwd):/data \
  --entrypoint /usr/src/app/tilemaker-server \
  ghcr.io/systemed/tilemaker:master \
  /data/output.mbtiles --static /usr/src/app/server/static
```

--------------------------------

### Lua Initialization and Exit Functions

Source: https://github.com/systemed/tilemaker/blob/master/docs/CONFIGURATION.md

Define Lua functions to be executed at the start and end of Tilemaker processing. These functions can be used for tasks like outputting statistics or loading external data, with `init_function` receiving a flag indicating if it's the first call.

```lua
function init_function(name, is_first)
  -- Initialization logic here
  if is_first then
    print("Initializing for the first time.")
  end
end

function exit_function()
  -- Exit logic here
  print("Exiting processing.")
end
```

--------------------------------

### Configure Layers with write_to in Tilemaker

Source: https://github.com/systemed/tilemaker/blob/master/docs/CONFIGURATION.md

Demonstrates how to use the 'write_to' parameter to combine multiple layer specifications into a single output layer. This allows for merging features from different zoom levels or sources into one cohesive layer, with options for simplification.

```json
{
  "layers": {
    "roads": { "minzoom": 12, "maxzoom": 14 },
    "low_roads": { "minzoom": 9, "maxzoom": 11, "write_to": "roads", "simplify_below": 12, "simplify_level": 0.0001 }
  }
}
```

--------------------------------

### Initialize Mapbox GL JS Map with Tilemaker Styles

Source: https://github.com/systemed/tilemaker/blob/master/server/static/index.html

This JavaScript code initializes a Mapbox GL JS map. It fetches metadata to determine the map's center and zoom level, then sets the map style using a URL provided by Tilemaker. It also adds navigation and attribution controls.

```javascript
var map;
fetch("/metadata")
  .then(response => response.json())
  .then(data => {
    var styleURL = window.location.protocol+'//'+window.location.host+'/style.json';
    var bounds = data['bounds'].split(',');
    map = new mapboxgl.Map({
      container: 'map',
      style: styleURL,
      center: [(Number(bounds[0])+Number(bounds[2]))/2, (Number(bounds[1])+Number(bounds[3]))/2],
      zoom: 13
    });

    map.addControl(new mapboxgl.NavigationControl());
    map.addControl(new mapboxgl.AttributionControl({
      compact: false,
      customAttribution: "Style © <a href='http://openmaptiles.org/'>OpenMapTiles</a> | " +
                         "Data © <a href='http://www.openstreetmap.org/copyright'>OpenStreetMap contributors</a>"
    }));

    // -- Comment the following lines out to remove debug UI --
    map.showTileBoundaries=true;
    map.addControl(new MapboxInspect({ showInspectButton: false, showMapPopup: true }));
    // -- --
  })
```

--------------------------------

### Project Setup and Build Type Configuration (CMake)

Source: https://github.com/systemed/tilemaker/blob/master/CMakeLists.txt

Initializes the CMake build system, sets the default build type to 'Release' if not specified, and defines the project name. It also configures module paths and enforces out-of-source builds.

```cmake
cmake_minimum_required(VERSION 3.18)

if(NOT CMAKE_BUILD_TYPE)
  set(CMAKE_BUILD_TYPE "Release")
endif()

project(tilemaker)

OPTION(TILEMAKER_BUILD_STATIC "Attempt to link dependencies static" OFF)

list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake")

if("${PROJECT_SOURCE_DIR}" STREQUAL "${PROJECT_BINARY_DIR}")
  message(FATAL_ERROR "In-source builds are not allowed, please use a separate build directory.")
endif()

if (POLICY CMP0074)
  cmake_policy(SET CMP0074 NEW)
endif()
```

--------------------------------

### Basic Road/Path Layering in Lua

Source: https://github.com/systemed/tilemaker/blob/master/docs/CONFIGURATION.md

This Lua function demonstrates the fundamental process of identifying 'highway' tags in OSM objects and writing them to a 'roads' layer. It also adds 'name' and 'type' attributes to the features. This is a simple example for including roads and paths.

```lua
function way_function()
  local highway = Find("highway")
  if highway~="" then
    Layer("roads", false)
    Attribute("name", Find("name"))
    Attribute("type", highway)
  end
end
```

--------------------------------

### CSS for Refresh Button

Source: https://github.com/systemed/tilemaker/blob/master/server/static/index.html

This CSS styles a refresh button positioned absolutely within the map container, providing basic styling for its appearance and behavior.

```css
#refresh { position: absolute; top: 15px; left: 15px; background-color: white; padding: 5px; border: 1px solid black; font-family: Avenir; cursor: pointer; }
```

--------------------------------

### Add Custom Metadata to MBTiles with Tilemaker

Source: https://github.com/systemed/tilemaker/blob/master/docs/CONFIGURATION.md

Shows how to include additional metadata fields in the MBTiles output by using the 'metadata' entry under 'settings'. This is useful for adding information like author, license, or layer ordering, adhering to the MBTiles 1.3 spec.

```json
{
  "layers": { ... },
  "settings": {
    "metadata": {
      "author": "THERE Data Inc",
      "licence": "ODbL 1.1",
      "layer_order": { "water": 1, "buildings": 2, "roads": 3 }
    }
  }
}
```

--------------------------------

### Lua Script for Filtering Ways by Tag

Source: https://github.com/systemed/tilemaker/blob/master/docs/RUNNING.md

Demonstrates how to filter OSM objects in a Lua processing script for tilemaker. This example shows how to include only major roads, railways, or exclude buildings.

```lua
-- Only include major roads
way_keys = {"highway=motorway", "highway=trunk", "highway=primary", "highway=secondary"}
```

```lua
-- Only include railways
way_keys = {"railway"}
```

```lua
-- Include everything but not buildings
way_keys = {"~building"}
```

--------------------------------

### C++ Standard and Version Definition (CMake)

Source: https://github.com/systemed/tilemaker/blob/master/CMakeLists.txt

Sets the C++ standard to C++17. If the TM_VERSION macro is not defined, it attempts to get the Git tag and defines TM_VERSION for the compiler.

```cmake
set(CMAKE_CXX_STANDARD 17)

if(!TM_VERSION)
	execute_process(
		COMMAND git describe --tags --abbrev=0
		OUTPUT_VARIABLE tm_version)
	add_compile_definitions(TM_VERSION=${tm_version})
endif()
```

--------------------------------

### Lua Node and Way Filtering Configuration

Source: https://github.com/systemed/tilemaker/blob/master/docs/CONFIGURATION.md

Configure which OSM nodes and ways are processed by Tilemaker using Lua tables for keys. This allows for efficient filtering to focus on relevant data, improving processing performance.

```lua
node_keys = { "highway", "railway" }

way_keys = {"~building"}
-- or
way_keys = {"highway=motorway", "highway=trunk", "highway=primary", "highway=secondary"}
```

--------------------------------

### Lua Processing Functions for Tilemaker

Source: https://github.com/systemed/tilemaker/blob/master/docs/CONFIGURATION.md

Outlines the available Lua functions that can be implemented in a processing script for Tilemaker. These functions allow for custom handling of OSM nodes, ways, and relations, including initialization, exit routines, and attribute remapping.

```lua
-- Optional: List of OSM tags indicating a node should be processed
node_keys = { "amenity", "shop", "natural" }

-- Optional: List of OSM tags indicating a way should be processed
way_keys = { "highway", "landuse", "natural" }

-- Function to process an OSM node
function node_function(node)
  -- Add node to layers here
end

-- Function to process an OSM way
function way_function(way)
  -- Add way to layers here
end

-- Optional: Function to initialize Lua logic
function init_function(name, is_first)
  -- Initialization code
end

-- Optional: Function to finalize Lua logic
function exit_function()
  -- Finalization code, e.g., print statistics
end

-- Optional: Function to determine if a relation should be processed
function relation_scan_function(relation)
  -- Return true if relation should be processed
  return false
end

-- Function to process an OSM relation
function relation_function(relation)
  -- Add relation to layers here
end

-- Optional: Function to remap attributes from shapefiles
function attribute_function(attributes)
  -- Remap attributes here
end
```

--------------------------------

### Tilemaker CLI: Full Options with Config and Process Scripts

Source: https://context7.com/systemed/tilemaker/llms.txt

This command shows a more comprehensive usage of the tilemaker CLI, specifying input and output files, along with custom configuration and processing Lua scripts. This allows for detailed control over layer definition and feature processing.

```bash
# Full command with explicit options
tilemaker --input oxfordshire.osm.pbf \
          --output oxfordshire.mbtiles \
          --config resources/config-openmaptiles.json \
          --process resources/process-openmaptiles.lua
```

--------------------------------

### Automate Tile Generation with GitHub Actions

Source: https://context7.com/systemed/tilemaker/llms.txt

YAML configuration for GitHub Actions to automate vector tile generation. Includes steps for checking out code, downloading OSM data, using the Tilemaker action with various options (input, output, config, process, extra arguments), and uploading artifacts. An alternative for PMTiles output is also shown.

```yaml
# .github/workflows/generate-tiles.yml
name: Generate Vector Tiles

on:
  push:
    branches: [main]
  workflow_dispatch:

jobs:
  generate-tiles:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Download OSM data
        run: |
          wget https://download.geofabrik.de/europe/monaco-latest.osm.pbf

      - name: Generate vector tiles
        uses: systemed/tilemaker@v2.0.0
        with:
          # Required: input PBF file
          input: monaco-latest.osm.pbf
          # Required: output file or directory
          output: monaco.mbtiles
          # Optional: config file (defaults to resources/config-openmaptiles.json)
          config: resources/config-openmaptiles.json
          # Optional: Lua processing script
          process: resources/process-openmaptiles.lua
          # Optional: additional arguments
          extra: --verbose --threads 0

      - name: Upload tiles artifact
        uses: actions/upload-artifact@v4
        with:
          name: vector-tiles
          path: monaco.mbtiles

  # Alternative: PMTiles output for cloud hosting
  generate-pmtiles:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Download OSM data
        run: wget https://download.geofabrik.de/europe/liechtenstein-latest.osm.pbf

      - uses: systemed/tilemaker@v2.0.0
        with:
          input: liechtenstein-latest.osm.pbf
          output: liechtenstein.pmtiles
          extra: --verbose

      - name: Deploy to cloud storage
        run: |
          # Upload to S3, GCS, or other cloud storage
          aws s3 cp liechtenstein.pmtiles s3://my-tiles-bucket/
```

--------------------------------

### Lua Spatial Query: AreaIntersecting

Source: https://github.com/systemed/tilemaker/blob/master/docs/CONFIGURATION.md

Calculate the area of intersection between the current way and features in a specified shapefile or GeoJSON layer using the `AreaIntersecting` Lua function. This is useful for quantitative spatial analysis.

```lua
-- Calculate intersection area with 'ocean' layer
local intersection_area = AreaIntersecting("ocean")
print("Intersection area: " .. intersection_area)
```

--------------------------------

### Standard Tile Generation with Tilemaker

Source: https://github.com/systemed/tilemaker/blob/master/docs/RUNNING.md

Generates vector tiles from an OpenStreetMap .pbf extract using a configuration file and a Lua processing script. Outputs to an .mbtiles file.

```bash
tilemaker --input oxfordshire.osm.pbf \
          --output oxfordshire.mbtiles \
          --config resources/config-openmaptiles.json \
          --process resources/process-openmaptiles.lua
```

--------------------------------

### Lua Spatial Query: FindIntersecting

Source: https://github.com/systemed/tilemaker/blob/master/docs/CONFIGURATION.md

Use the `FindIntersecting` function in Lua to retrieve a list of intersecting features from a shapefile or GeoJSON layer. This function requires `index: true` and `index_column` to be set for the layer.

```lua
-- Assuming 'countries' layer is configured with index: true and index_column
local names = FindIntersecting("countries")
print(table.concat(names, ","))
```

--------------------------------

### Shapefile and GeoJSON Layer Configuration

Source: https://github.com/systemed/tilemaker/blob/master/docs/CONFIGURATION.md

Configure Tilemaker to import data from shapefile (.shp) or GeoJSON files. This allows integrating external datasets like coastlines or urban area outlines into the vector tiles.

```json
"urban_areas": {
  "minzoom": 11, "maxzoom": 14,
  "source": "data/urban_areas.shp",
  "simplify_below": 13, "simplify_level": 0.0003
},
"bridges": {
  "minzoom": 13, "maxzoom": 14,
  "source": "data/Bridges_WGS84.shp", 
  "source_columns": ["SAP_DESCRI"]
}
```

--------------------------------

### Docker Usage: Running Tilemaker Server

Source: https://context7.com/systemed/tilemaker/llms.txt

This Docker command demonstrates how to run the `tilemaker-server` component within a container. It mounts an existing .mbtiles file for serving vector tiles.

```bash
# Run tilemaker-server in Docker
docker run -it --rm -v $(pwd):/data \
  --entrypoint /usr/src/app/tilemaker-server \
  ghcr.io/systemed/tilemaker:master \
  /data/output.mbtiles
```

--------------------------------

### Basic SQLite Operations in C++

Source: https://github.com/systemed/tilemaker/blob/master/include/external/README_sqlite_cpp.md

Demonstrates basic database operations including creating a table, inserting data, selecting data with conditions, and counting records. It uses RAII for database connections and lambda functions for processing query results. Supports UTF-16 strings.

```c++
#include<iostream>
#include "sqlite_modern_cpp.h"
using namespace  sqlite;
using namespace std;


	try {
		// creates a database file 'dbfile.db' if it does not exists.
		database db("dbfile.db");

		// executes the query and creates a 'user' table
		db <<
			"create table if not exists user (

```

```c++
			"\t_id integer primary key autoincrement not null,\n"
			"\tage int,\n"
			"\tname text,\n"
			"\tweight real\n"
			">
			;

		// inserts a new user record.
		// binds the fields to '?' .
		// note that only types allowed for bindings are :
		//		int ,long, long long, float, double
		//		string , u16string
		// sqlite3 only supports utf8 and utf16 strings, you should use std::string for utf8 and std::u16string for utf16.
		// note that u"my text" is a utf16 string literal of type char16_t * .
		db << "insert into user (age,name,weight) values (?,?,?);"
			<< 20
			<< u"bob" // utf16 string
			<< 83.25f;

		db << u"insert into user (age,name,weight) values (?,?,?);" // utf16 query string
			<< 21
			<< "jack"
			<< 68.5;
			
		cout << "The new record got assigned id " << db.last_insert_rowid() << endl;

		// slects from user table on a condition ( age > 18 ) and executes
		// the lambda for each row returned .
		db << "select age,name,weight from user where age > ? ;"
			<< 18
			>> [&](int age, string name, double weight) {
			cout << age << ' ' << name << ' ' << weight << endl;
		};

		// selects the count(*) from user table
		// note that you can extract a single culumn single row result only to : int,long,long,float,double,string,u16string
		int count = 0;
		db << "select count(*) from user" >> count;
		cout << "cout : " << count << endl;

		// this also works and the returned value will be automatically converted to string
		string str_count;
		db << "select count(*) from user" >> str_count;
		cout << "scount : " << str_count << endl;
	}
	catch (exception& e) {
		cout << e.what() << endl;
	}

```

--------------------------------

### Lua Attribute Transformation for Shapefiles/GeoJSON

Source: https://github.com/systemed/tilemaker/blob/master/docs/CONFIGURATION.md

Implement a Lua `attribute_function` to transform attributes from imported shapefile or GeoJSON layers. This function receives shapefile attributes and the layer name, returning a table of attributes for the vector tile.

```lua
function attribute_function(attr, layer)
  -- Process attributes (attr) and return a new table
  local new_attrs = {}
  new_attrs.name = attr.NAME
  if layer == "urban_areas" then
    new_attrs._minzoom = 12 -- Example: set minzoom dynamically
  end
  return new_attrs
end
```

--------------------------------

### Handling NULL Values with Boost.Optional in C++

Source: https://github.com/systemed/tilemaker/blob/master/include/external/README_sqlite_cpp.md

Shows how to use `boost::optional` to handle potential NULL values in database columns. This requires including the `boost_optional.h` extension. It allows for seamless mapping between C++ optional types and SQL NULLs.

```c++
	#include "sqlite_modern_cpp.h"
	#include "extensions/boost_optional.h"
	
	struct User {
		long long _id;
		boost::optional<int> age;
		boost::optional<string> name;
		boost::optional<real> weight;
	};
	
	{
		User user;
		user.name = "bob";
		
		// Same database as above
		database db("dbfile.db");
		
		// Here, age and weight will be inserted as NULL in the database.
		db << "insert into user (age,name,weight) values (?,?,?);"
			<< user.age
			<< user.name
			<< user.weight;
			
		user._id = db.last_insert_rowid();
	}
	
	{
		// Here, the User instance will retain the NULL value(s) from the database.
		db << "select _id,age,name,weight from user where age > ? ;"
			<< 18
			>> [&](long long id,
				boost::optional<int> age, 
				boost::optional<string> name
				boost::optional<real> weight) {
			
			User user;
			user._id = id;
			user.age = age;
			user.name = move(name);
			user.weight = weight;
			
			cout << "id=" << user._id
				<< " age = " << (user.age ? to_string(*user.age) ? string("NULL"))
				<< " name = " << (user.name ? *user.name : string("NULL"))
				<< " weight = " << (user.weight ? to_string(*user.weight) : string(NULL))
				<< endl;
		};
	}

```

--------------------------------

### Lua Spatial Query: Intersects

Source: https://github.com/systemed/tilemaker/blob/master/docs/CONFIGURATION.md

Perform a spatial query using the `Intersects` function in Lua to check if a current OSM object is within a specified shapefile or GeoJSON layer. This requires the layer to have `index: true` enabled.

```lua
-- Assuming 'countries' layer is configured with index: true
if Intersects("countries") then 
  print("Looks like it's on land"); 
end
```

--------------------------------

### Lua Spatial Query: CoveredBy and FindCovering

Source: https://github.com/systemed/tilemaker/blob/master/docs/CONFIGURATION.md

Utilize `CoveredBy` and `FindCovering` Lua functions for spatial queries, checking if an object is covered by or finding objects that cover it within a specified shapefile or GeoJSON layer. These also require indexing.

```lua
-- Check if current object is covered by a layer
if CoveredBy("some_layer") then
  print("Object is covered.")
end

-- Find objects that cover the current object
local covering_objects = FindCovering("another_layer")
print("Found " .. #covering_objects .. " covering objects.")
```

--------------------------------

### Docker Usage: Basic Tilemaker with PMTiles Output

Source: https://context7.com/systemed/tilemaker/llms.txt

This Docker command demonstrates running tilemaker within a container to convert an OSM PBF file to PMTiles format. It mounts the current directory as a volume for input/output access and uses the latest `tilemaker:master` image.

```bash
# Basic Docker usage with default OpenMapTiles config
docker run -it --rm -v $(pwd):/data ghcr.io/systemed/tilemaker:master \
  /data/monaco-latest.osm.pbf \
  --output /data/monaco-latest.pmtiles
```

--------------------------------

### Fast Tile Generation with Tilemaker

Source: https://github.com/systemed/tilemaker/blob/master/docs/RUNNING.md

Enables faster tile generation at the expense of slightly increased memory usage. This option optimizes performance for users with sufficient RAM.

```bash
tilemaker --input data.osm.pbf \
          --output data.mbtiles \
          --config resources/config.json \
          --process resources/process.lua \
          --fast
```

--------------------------------

### Tilemaker CLI: Basic OSM to MBTiles Conversion

Source: https://context7.com/systemed/tilemaker/llms.txt

This command demonstrates the basic usage of the tilemaker CLI to convert an OpenStreetMap .osm.pbf file into an .mbtiles container. It requires the input PBF file path and the desired output .mbtiles file path.

```bash
# Basic usage - convert OSM data to mbtiles
tilemaker /path/to/input.osm.pbf /path/to/output.mbtiles
```

--------------------------------

### Tilemaker CLI: Compact Mode for Sequential PBFs

Source: https://context7.com/systemed/tilemaker/llms.txt

This command activates 'compact mode' with the `--compact` flag, which is optimized for processing sequentially ordered PBF files. This mode can improve efficiency when dealing with PBF files that are already sorted.

```bash
# Compact mode for sequentially-ordered PBFs
tilemaker /path/to/input.osm.pbf /path/to/output.mbtiles --compact
```

--------------------------------

### Platform-Specific SQLite3 and Defines (CMake)

Source: https://github.com/systemed/tilemaker/blob/master/CMakeLists.txt

Handles SQLite3 library discovery and adds platform-specific preprocessor definitions. It uses 'unofficial-sqlite3' for MSVC and 'SQLite3' for other platforms, and defines specific macros for Windows builds.

```cmake
if(MSVC)
 	find_package(unofficial-sqlite3 CONFIG REQUIRED)
	add_library(SQLite::SQLite3 ALIAS unofficial::sqlite3::sqlite3)
	add_definitions(-D_USE_MATH_DEFINES -DWIN32_LEAN_AND_MEAN -DNOGDI -D__restrict__=__restrict)
  	set(THREAD_LIB "")
else()
	find_package(SQLite3 REQUIRED)
  	set(THREAD_LIB pthread)
endif()
```

--------------------------------

### Tilemaker CLI: Processing Multiple PBF Files

Source: https://context7.com/systemed/tilemaker/llms.txt

This command demonstrates how to process multiple OpenStreetMap .osm.pbf files simultaneously and merge their output into a single .mbtiles container. This is useful for combining data from different regions or sources.

```bash
# Process multiple PBF files
tilemaker australia.osm.pbf new-zealand.osm.pbf --output oceania.mbtiles
```

--------------------------------

### Tilemaker Lua Scripting for Feature Logic

Source: https://github.com/systemed/tilemaker/blob/master/docs/CONFIGURATION.md

A Lua script used by tilemaker to assign OpenStreetMap data to layers based on tags. This script defines the logic for categorizing features like roads, railways, and buildings into respective layers within the vector tiles.

```lua
-- Example Lua script snippet (actual code not provided in text)
-- Assign features based on tags
if feature.tags['highway'] then
  return 'roads'
elseif feature.tags['railway'] then
  return 'railway'
-- ... other layer assignments
end
```

--------------------------------

### Set Data in Lua Key/Value Store

Source: https://github.com/systemed/tilemaker/blob/master/docs/CONFIGURATION.md

Demonstrates how to set a key-value pair in Tilemaker's Lua key/value store. This function is typically called within an `init_function` to load external data. Both the key and value must be strings. The `SetData` function is used for this purpose.

```lua
function init_function(is_first)
  if is_first then
    -- Read data from file using Lua's I/O functions
    -- For example:
    local file = io.open("my_data.txt", "r")
    if file then
      local content = file:read("*a")
      io.close(file)
      SetData("external_data", content)
    end
    -- Set a simple string value
    SetData("name", "Bill")
  end
end
```

--------------------------------

### Create Global Coastline MBTiles with Tilemaker

Source: https://github.com/systemed/tilemaker/blob/master/docs/RUNNING.md

Generates a global coastline .mbtiles file using a stripped-down configuration. This command requires specifying the output file, bounding box, process file, and configuration file.

```bash
tilemaker --output coastline.mbtiles \
          --bbox -180,-85,180,85 \
          --process resources/process-coastline.lua \
          --config resources/config-coastline.json
```

--------------------------------

### Run tilemaker with Docker (Basic)

Source: https://github.com/systemed/tilemaker/blob/master/README.md

This command runs tilemaker using a Docker image to generate Protomaps vector tiles from an OpenStreetMap snapshot. It mounts the current directory to `/data` inside the container and outputs the tiles to `monaco-latest.pmtiles`.

```bash
docker run -it --rm -v $(pwd):/data ghcr.io/systemed/tilemaker:master /data/monaco-latest.osm.pbf --output /data/monaco-latest.pmtiles
```

--------------------------------

### External Library Discovery (CMake)

Source: https://github.com/systemed/tilemaker/blob/master/CMakeLists.txt

Finds and configures necessary external libraries including libshp, Rapidjson, and Lua/LuaJIT. It includes conditional logic to handle the presence of Lua or LuaJIT and sets appropriate include directories and definitions.

```cmake
find_package(libshp REQUIRED)

find_package(Rapidjson REQUIRED)

find_package(Lua)

if(LUA_FOUND)
	include_directories(${LUA_INCLUDE_DIR})
else()
	find_package(LuaJIT REQUIRED)
	add_definitions(-DLUAJIT)
	include_directories(${LUAJIT_INCLUDE_DIR})
endif()
```

--------------------------------

### Lua Tag Reading Functions for OSM Data

Source: https://context7.com/systemed/tilemaker/llms.txt

Provides functions for reading and checking OpenStreetMap tags on the current node or way being processed. It includes functions to find tag values, check for tag existence, retrieve all keys and tags, and get the OSM object ID and type.

```lua
function way_function()
    -- Find(key): returns tag value or empty string
    local highway = Find("highway")
    local name = Find("name")
    local maxspeed = Find("maxspeed")

    -- Holds(key): returns true if tag exists
    if Holds("bridge") then
        AttributeBoolean("bridge", true)
    end

    -- Check for empty values
    if highway ~= "" then
        Layer("roads", false)
        Attribute("type", highway)
    end

    -- AllKeys(): returns table of all tag keys
    local keys = AllKeys()
    for i, key in ipairs(keys) do
        print("Key: " .. key)
    end

    -- AllTags(): returns table of all tags {key = value}
    local tags = AllTags()
    for key, value in pairs(tags) do
        print(key .. " = " .. value)
    end

    -- Id(): get OSM object ID
    local osm_id = Id()

    -- OsmType(): get object type ("node", "way", "relation")
    local osm_type = OsmType()
end
```

--------------------------------

### SQLite Transactions in C++

Source: https://github.com/systemed/tilemaker/blob/master/include/external/README_sqlite_cpp.md

Illustrates how to manage database transactions using 'begin;', 'commit;', and 'rollback;' commands. This allows for atomic operations, ensuring data integrity by grouping multiple SQL statements.

```c++
	db << "begin;"; // begin a transaction ...   
	db << "insert into user (age,name,weight) values (?,?,?);"
			<< 20
			<< u"bob"
			<< 83.25f;
	db << "insert into user (age,name,weight) values (?,?,?);" // utf16 string
			<< 21
			<< u"jack"
			<< 68.5;
	db << "commit;"; // commit all the changes.
                
	db << "begin;"; // begin another transaction ....
	db << "insert into user (age,name,weight) values (?,?,?);" // utf16 string
			<< 19
			<< u"chirs"
			<< 82.7;
	db << "rollback;"; // cancel this transaction ...

```

--------------------------------

### Tilemaker CLI: Output Tiles Directly to Filesystem

Source: https://context7.com/systemed/tilemaker/llms.txt

This command demonstrates outputting vector tiles directly to a specified directory on the filesystem, rather than packaging them into a single container file. This can be useful for certain deployment scenarios.

```bash
# Output tiles directly to filesystem
tilemaker /path/to/input.osm.pbf /path/to/tiles/
```

--------------------------------

### Tile Generation with On-Disk Storage

Source: https://github.com/systemed/tilemaker/blob/master/docs/RUNNING.md

Generates vector tiles using on-disk storage to reduce RAM requirements. This is beneficial for processing large OpenStreetMap extracts on memory-constrained systems.

```bash
tilemaker --input large-area.osm.pbf \
          --output large-area.mbtiles \
          --config resources/config.json \
          --process resources/process.lua \
          --store /path/to/temp/store
```

--------------------------------

### Download Coastline Data

Source: https://github.com/systemed/tilemaker/blob/master/README.md

This command downloads coastline data required for generating sea tiles and small-scale landcover. It requires approximately 2GB of disk space.

```bash
./get-coastline.sh
```

--------------------------------

### Tilemaker CLI: On-Disk Storage for Large Areas

Source: https://context7.com/systemed/tilemaker/llms.txt

This command utilizes the `--store` option to specify an on-disk storage location for processing large OSM datasets. This significantly reduces RAM usage, making it feasible to process extensive geographical areas.

```bash
# Use on-disk storage for large areas (reduces RAM usage)
tilemaker /path/to/input.osm.pbf /path/to/output.mbtiles --store /path/to/ssd
```

--------------------------------

### Linking Libraries for tilemaker Executable (CMake)

Source: https://github.com/systemed/tilemaker/blob/master/CMakeLists.txt

Links the necessary libraries to the 'tilemaker' executable, including threading, dynamic loading, Lua, SQLite3, Rapidjson, and Boost components. It conditionally links the Boost.System library if BOOST_HAS_SYSTEM is true.

```cmake
target_link_libraries(tilemaker
		${THREAD_LIB} ${CMAKE_DL_LIBS}
		${LUA_LIBRARIES}
		shapelib::shp
		SQLite::SQLite3
		Rapidjson::rapidjson
		Boost::filesystem Boost::program_options)
if(BOOST_HAS_SYSTEM)
	target_link_libraries(tilemaker Boost::system)
endif()
```

--------------------------------

### Tilemaker CLI: Fast Mode for Speed Prioritization

Source: https://context7.com/systemed/tilemaker/llms.txt

This command enables 'fast mode' using the `--fast` flag, which prioritizes processing speed over memory consumption. This can be beneficial when quick tile generation is required, potentially at the cost of higher memory usage.

```bash
# Fast mode - prioritize speed over memory
tilemaker /path/to/input.osm.pbf /path/to/output.mbtiles --fast
```

--------------------------------

### Docker Usage: Build Tilemaker Image Locally

Source: https://context7.com/systemed/tilemaker/llms.txt

This command builds the Tilemaker Docker image locally from the current directory's Dockerfile. This allows for custom builds or development versions of the tool.

```bash
# Build Docker image locally
docker build . -t tilemaker
```