typconv

typconv - Garmin TYP Converter

Native Linux tool for converting Garmin TYP (custom map type) files between binary and text formats.

Features

• ✅ Binary TYP → Text: Convert binary TYP files to mkgmap-compatible text format
• ✅ Text → Binary TYP: Create binary TYP files from text definitions
• ✅ Extract from .img: Extract TYP files from Garmin .img container files
• ✅ Round-trip Conversion: Full bidirectional conversion with data preservation
• ✅ Character Encoding: Automatic CodePage detection and support for all Windows codepages
• ✅ No Wine required: Pure Go implementation, works natively on Linux
• ✅ Library support: Can be used as a Go library in other projects

Why typconv?

Currently, the only tool that can convert binary TYP files to text is img2typ, a Windows-only application. Linux users must either:

• Use Wine to run Windows tools
• Manually hex-edit binary files
• Give up on customizing maps from .img files

typconv changes this by providing the first open-source, native Linux implementation of the binary TYP format.

Installation

From Source

git clone https://github.com/dyuri/typconv
cd typconv
go build -o build/typconv ./cmd/typconv

Using Go

go install github.com/dyuri/typconv/cmd/typconv@latest

Quick Start

Convert Binary to Text

# Convert a binary TYP file to text format
typconv bin2txt map.typ -o map.txt

# Convert to JSON format
typconv bin2txt map.typ --format json -o map.json

# Convert and display to stdout
typconv bin2txt map.typ

Convert Text to Binary

# Convert text format to binary TYP
# CodePage is automatically detected from the text file header
typconv txt2bin custom.txt -o custom.typ

# Override FID and PID if needed
typconv txt2bin custom.txt -o custom.typ --fid 3511 --pid 1

# Override CodePage (only if you need to force a specific encoding)
typconv txt2bin custom.txt -o custom.typ --codepage 1250

Display File Information

# Show detailed file information
typconv info map.typ

# Brief one-line summary (great for batch processing)
typconv info map.typ --brief

# JSON output for scripting
typconv info map.typ --json

Validate Files

# Validate TYP file structure
typconv validate map.typ

# Strict validation (fail on warnings, useful for CI/CD)
typconv validate map.typ --strict

Extract from IMG Files

# List TYP files in a Garmin IMG container
typconv extract gmapsupp.img --list

# Extract first TYP file to a directory
typconv extract gmapsupp.img -o output_dir

# Extract all TYP files (if multiple exist)
typconv extract gmapsupp.img -o output_dir --all

Round-Trip Conversion

# Binary → Text → Binary preserves all data
typconv bin2txt original.typ -o temp.txt
typconv txt2bin temp.txt -o recreated.typ
typconv bin2txt recreated.typ -o verify.txt

# temp.txt and verify.txt should be identical

Usage

Commands

typconv [command] [flags] [arguments]

Available Commands:
  bin2txt      Convert binary TYP to text format
  txt2bin      Convert text format to binary TYP
  extract      Extract TYP files from .img containers
  info         Display TYP file information
  validate     Validate TYP file structure
  version      Show version information
  help         Show help for any command

bin2txt Flags

  -o, --output FILE     Output file path (default: stdout)
  --format FORMAT       Output format: mkgmap (default), json
  --no-xpm             Skip XPM bitmap data
  --no-labels          Skip label strings

txt2bin Flags

  -o, --output FILE      Output file path (required)
  --fid NUMBER          Override Family ID
  --pid NUMBER          Override Product ID
  --codepage NUMBER     Override character encoding (auto-detected by default)

Note: The --codepage flag is optional. If not specified, typconv automatically reads the CodePage from the [_id] section of your text file.

extract Flags

  -o, --output DIR         Output directory (required for extraction)
  -l, --list              List TYP files without extracting
  --all                   Extract all TYP files (default: first only)

info Flags

  --json               Output as JSON
  --brief              Show only summary (one-line format)

validate Flags

  --strict             Fail on warnings (useful for CI/CD)

Character Encoding

typconv automatically detects and uses the correct character encoding:

CodePage	Encoding	Languages
1252	Windows-1252	Western European
1250	Windows-1250	Central European (Hungarian)
1251	Windows-1251	Cyrillic
437	CP437	Original IBM PC

The text files are always UTF-8 encoded, and typconv handles the conversion automatically.

Use as a Library

package main

import (
    "os"
    "github.com/dyuri/typconv/pkg/typconv"
)

func main() {
    // Parse binary TYP file
    f, _ := os.Open("map.typ")
    defer f.Close()

    stat, _ := f.Stat()
    typ, err := typconv.ParseBinaryTYP(f, stat.Size())
    if err != nil {
        panic(err)
    }

    // Write to text format
    out, _ := os.Create("map.txt")
    defer out.Close()
    typconv.WriteTextTYP(out, typ)

    // Write back to binary
    outBin, _ := os.Create("map_new.typ")
    defer outBin.Close()
    typconv.WriteBinaryTYP(outBin, typ)
}

Examples

Working with Real Maps

# Convert OpenHiking TYP to text for editing
typconv bin2txt openhiking.typ -o editable.txt

# Edit editable.txt with your favorite text editor
vim editable.txt

# Convert back to binary
typconv txt2bin editable.txt -o custom.typ

Batch Processing

# Convert all TYP files in a directory to text
for f in *.typ; do
    typconv bin2txt "$f" -o "${f%.typ}.txt"
done

# Get quick info on all TYP files
for f in *.typ; do
    typconv info "$f" --brief
done

# Validate all TYP files
for f in *.typ; do
    echo "Validating $f..."
    typconv validate "$f" || echo "FAILED: $f"
done

JSON Processing

# Convert to JSON for analysis
typconv bin2txt map.typ --format json -o map.json

# Query with jq
typconv bin2txt map.typ --format json | jq '.points | length'
typconv bin2txt map.typ --format json | jq '.header.codepage'

# Extract all point types
typconv bin2txt map.typ --format json | jq '.points[].type'

Text Format

typconv uses the mkgmap text format, which is compatible with the mkgmap compiler:

[_id]
CodePage=1252
FID=3511
ProductCode=1
[end]

[_point]
Type=0x2f06
SubType=0x00
String1=0x04,Trail Junction
String1=0x14,Főváros
DayColor=#ff0000
NightColor=#ff0000
DayXpm="8 8 2 1"
"! c #ff0000"
"  c none"
"!!!!!!!!"
"!      !"
"!      !"
"!      !"
"!      !"
"!      !"
"!      !"
"!!!!!!!!"
[end]

Project Status

Status: Core functionality complete and production-ready ✅

Completed Features

• ✅ Binary TYP reader (parser)
• ✅ Text format writer (mkgmap-compatible)
• ✅ Text format reader
• ✅ Binary TYP writer
• ✅ Full round-trip conversion (binary ↔ text)
• ✅ CLI framework with cobra
• ✅ Character encoding support (all Windows codepages)
• ✅ Automatic CodePage detection
• ✅ XPM bitmap handling (day/night patterns)
• ✅ Multi-language label support
• ✅ JSON output format (bin2txt --format json)
• ✅ info command - Display TYP file metadata
• ✅ validate command - Validate TYP file structure
• ✅ extract command - Extract TYP files from .img containers
• ✅ Comprehensive test suite

All core features are complete: typconv provides a complete toolset for working with Garmin TYP files on Linux, including conversion, extraction, inspection, validation, and JSON export.

Testing

Tested with real-world TYP files:

• OpenHiking: European hiking maps (402 points, 126 lines, 73 polygons)
• OpenMTBMap: Mountain bike maps
• Various CodePages: 1250 (Hungarian), 1252 (Western European), 437 (IBM PC)

All test files successfully complete round-trip conversion with 100% data preservation.

# Run test suite
go test ./...

Related Projects

• typtui: Terminal UI editor for TYP files (companion project)
• mkgmap: Compile OSM data into Garmin maps
• img2typ: Reference Windows implementation

Documentation

• Usage Guide: Comprehensive usage examples
• Binary Format: Reverse engineering notes
• AI Context: Project context for AI assistants

Resources

• mkgmap TYP Documentation
• OSM Wiki - Garmin Maps
• TYP Format Guide

Contributing

Contributions are welcome! This is an open-source implementation of a previously undocumented format.

Areas Where Help is Needed

• Testing with diverse TYP files from different map sources
• Implementation of .img container extraction
• Additional validation features
• Cross-platform testing (macOS, Windows)

License

MIT License - see LICENSE file for details.

Acknowledgments

• OpenStreetMap community for documentation and sample files
• mkgmap developers for the text format specification
• OpenHiking and OpenMTBMap projects for test files
• QMapShack project for binary format reference implementation

Author

Created by dyuri

---

Note: This project implements the complete binary TYP format through reverse engineering and analysis of real files. Round-trip conversion is tested and verified with real-world maps.