img2tilemap — Image → Godot 4 TileMap

Turn any tile-map PNG into a ready Godot 4 scene: it auto-detects the tile grid, deduplicates identical tiles, builds a TileSet + atlas, and reconstructs the whole map as a TileMapLayer. Run it from the command line or one-click from the Godot editor.

Features

• Automatic tile-size detection (8, 16, 24, 32, 48, 64 … or force it with --tile-size)
• Duplicate removal — identical tiles are merged by exact pixel match
• Emits a TileSet (.tres) + packed atlas (.png) and a TileMapLayer scene (.tscn)
• Collisions — --collisions adds colliders to opaque tiles (--collision-mode rect|alpha)
• Layers — --layers auto splits the map into layers by tile detail (experimental)
• Godot editor plugin — "Import Image to TileMap…" runs the whole thing in one click
• Godot 4.3+ (uses the TileMapLayer node). Pure Python core — no engine build step.

Quick start

python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt          # opencv-python, numpy
python importer.py --input examples/pixelcity.png --out ./godot_output

Output:

godot_output/
├── scenes/map.tscn
└── tiles/{tileset.png, tileset.tres}

Copy tiles/ and scenes/ into your Godot project (so they sit at res://tiles and res://scenes), let Godot import the PNG, and open scenes/map.tscn.

CLI

python importer.py --input city.png --out ./out                  # auto tile size
python importer.py --input city.png --tile-size 16 --out ./out
python importer.py --input city.png --collisions --layers auto --out ./out
python importer.py --input city.png --res-root res://maps/ --out ./maps

Godot editor plugin

Enable addons/img2tilemap in Project → Project Settings → Plugins, then Project → Tools → "Import Image to TileMap…", pick a PNG, set options, click Import!. (Needs Python 3.9+ with requirements.txt installed; point the Python field at your interpreter.)

Examples — when it shines, and when it doesn't

The dedup only pays off when the image is a real tile map (elements repeat on a grid). Same tool, two inputs:

Input	Cells	Unique tiles	Result
🎨 Pixel-art city (built from tiles)	1 408	24	crisp and a tiny reusable tileset — a real editable map
📷 Photoreal render	5 600	5 600	pixel-perfect copy, but every tile unique → useless as a tileset

A 2816×2048 pixel-art city collapses to a 24-tile set that reconstructs the whole map:

The entire tileset behind it (5×5 atlas, 24 tiles reused hundreds of times):

Takeaway: resolution controls sharpness, but tileability controls whether you get a useful tileset. Feed high-res pixel-art / tile-based maps for the best of both.

How it works

1. The image is sliced into tiles of the detected size.
2. Each tile is hashed by its raw pixels; identical tiles are merged.
3. The unique tiles are packed into one atlas texture.
4. A TileSet + TileMapLayer are generated from that table — the .tscn's tile_map_data byte layout is written to match Godot exactly, so the scene opens with zero re-import.

Development

.venv/bin/python -m pytest tests/ -q

License

MIT — see LICENSE.