Python Package Deployment

The Python package deployment allows you to use Maps4FS directly from Python code with full programmatic control over map generation. This approach is recommended for developers who want to integrate Maps4FS into their own applications or need advanced customization.

Features

🔴 Skill level: Advanced - Recommended for developers 🗺️ Supported map sizes: 2x2, 4x4, 8x8, 16x16 km and any custom size ✂️ Map scaling: Supported ⚙️ Advanced settings: Enabled 🖼️ Texture dissolving: Enabled

System Requirements

Python 3.8 or later
Git (for source code installation)
8 GB RAM for 2 km maps, 16 GB RAM for 4-8 km maps, 32 GB RAM for larger maps
SSD storage (will work very slow on HDD)
Windows 10/11 / Linux / MacOS

Step 1: Python Installation

Windows

Download Python:
- Go to python.org
- Download the latest Python 3.8+ installer (recommended: Python 3.11 or newer)
- Choose the "Windows installer (64-bit)" for most users
Install Python:
- Run the downloaded installer
- ⚠️ IMPORTANT: Check "Add Python to PATH" during installation
- Choose "Install Now" or "Customize installation"
- If customizing, ensure "pip" and "Add Python to environment variables" are selected
Verify installation:
```
python --version
pip --version
```
Both commands should return version information.

macOS

Option A: Official Installer (Recommended)
- Go to python.org
- Download the latest Python 3.8+ installer
- Run the .pkg file and follow the installation wizard

Option B: Using Homebrew

# Install Homebrew first if you don't have it
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Python
brew install python

Verify installation:
```
python3 --version
pip3 --version
```

Linux

Ubuntu/Debian:

# Update package list
sudo apt update

# Install Python and pip
sudo apt install python3 python3-pip python3-venv

# Verify installation
python3 --version
pip3 --version

CentOS/RHEL/Fedora:

# CentOS/RHEL
sudo yum install python3 python3-pip

# Fedora
sudo dnf install python3 python3-pip

# Verify installation
python3 --version
pip3 --version

Step 2: Git Installation (Optional, for source installation)

Windows

Go to git-scm.com
Download and run the installer
Use default settings during installation
Verify: git --version

macOS

# Option 1: Using Homebrew
brew install git

# Option 2: Using Xcode Command Line Tools
xcode-select --install

Linux

# Ubuntu/Debian
sudo apt install git

# CentOS/RHEL
sudo yum install git

# Fedora
sudo dnf install git

Step 3: Check Prerequisites

Before installing Maps4FS, verify your environment is ready:

Windows Command Prompt or PowerShell:

python --version
pip --version
git --version

macOS/Linux Terminal:

python3 --version
pip3 --version
git --version

All commands should return version information without errors.

Step 4: Create a Project Directory

It's recommended to create a dedicated directory for your Maps4FS project:

Windows:

mkdir C:\Maps4FS-Project
cd C:\Maps4FS-Project

macOS/Linux:

mkdir ~/Maps4FS-Project
cd ~/Maps4FS-Project

Step 5: Maps4FS Installation

There are two ways to install Maps4FS as a Python package:

Option 1: Install from PyPI (Recommended for Beginners)

Skill level: 🟡 Beginner-friendly Requires: Python, pip

This is the easiest and most reliable method:

Windows:

# Install Maps4FS
pip install maps4fs

# Verify installation
python -c "import maps4fs; print('Maps4FS installed successfully!')"

macOS/Linux:

# Install Maps4FS
pip3 install maps4fs

# Verify installation
python3 -c "import maps4fs; print('Maps4FS installed successfully!')"

Option 2: Install from Source Code (Advanced)

Skill level: 🔴 Advanced developers Requires: Python, pip, Git

For developers who want the latest features or need to modify the source code:

Windows:

# Clone the repository
git clone https://github.com/iwatkot/maps4fs.git
cd maps4fs

# Create virtual environment
python -m venv venv

# Activate virtual environment
venv\Scripts\activate

# Install dependencies
pip install -r dev/requirements.txt

# Install Maps4FS in development mode
pip install -e .

# Test installation
python demo.py

macOS/Linux:

# Clone the repository
git clone https://github.com/iwatkot/maps4fs.git
cd maps4fs

# Create virtual environment
python3 -m venv venv

# Activate virtual environment
source venv/bin/activate

# Install dependencies
pip install -r dev/requirements.txt

# Install Maps4FS in development mode
pip install -e .

# Test installation
python demo.py

💡 Even Easier: Automated Setup Scripts

Maps4FS includes convenient automation scripts that handle all the setup for you:

Windows (PowerShell):

# Clone the repository
git clone https://github.com/iwatkot/maps4fs.git
cd maps4fs

# Run the automated setup script
powershell -ExecutionPolicy Bypass -File dev/create_venv.ps1

# The script automatically:
# - Creates virtual environment
# - Activates it
# - Installs all dependencies
# - Sets up Maps4FS in development mode

# Test installation
python demo.py

macOS/Linux (Bash):

# Clone the repository
git clone https://github.com/iwatkot/maps4fs.git
cd maps4fs

# Run the automated setup script
bash dev/create_venv.sh

# The script automatically:
# - Creates virtual environment
# - Activates it
# - Installs all dependencies
# - Sets up Maps4FS in development mode

# Test installation
python demo.py

Benefits of automation scripts:

✅ One command setup - No need to remember multiple steps
✅ Error handling - Scripts check for prerequisites and handle common issues
✅ Consistent environment - Same setup every time
✅ Platform optimized - Different scripts for Windows vs Unix systems
✅ Time saving - Perfect for quick setup or CI/CD

💡 Pro Tip: Using Visual Studio Code

For the best development experience with source installation:

Install VS Code: Download from code.visualstudio.com

Open the project:

# After cloning the repository
cd maps4fs
code .  # Opens the project in VS Code

Install recommended extensions when prompted (Python extension)
Edit and run easily:
- Open demo.py in VS Code
- Modify coordinates, map size, or other parameters as needed
- Press F5 to run with debugger, or Ctrl+F5 to run without debugger
- The project includes pre-configured launch settings for easy debugging

This approach is perfect for:

Experimenting with different settings
Learning how Maps4FS works internally
Contributing to the project
Debugging generation issues

Virtual Environment (Recommended)

Using a virtual environment is highly recommended to avoid conflicts with other Python packages:

Windows:

# Create virtual environment
python -m venv maps4fs-env

# Activate it
maps4fs-env\Scripts\activate

# Install Maps4FS
pip install maps4fs

# When you're done, deactivate
deactivate

macOS/Linux:

# Create virtual environment
python3 -m venv maps4fs-env

# Activate it
source maps4fs-env/bin/activate

# Install Maps4FS
pip install maps4fs

# When you're done, deactivate
deactivate

Step 6: Download Required Data Templates

Maps4FS requires game templates and schemas to function properly. You need to download these files manually:

Download Method 1: Direct Download (Recommended)

Go to the Maps4FS repository: https://github.com/iwatkot/maps4fs
Click the green "Code" button → "Download ZIP"
Extract the ZIP file and copy the templates folder to your project directory

Download Method 2: Using Git

# Clone just the templates (if you only need data files)
git clone --depth 1 https://github.com/iwatkot/maps4fs.git temp-repo
cp -r temp-repo/templates ./templates
rm -rf temp-repo  # Clean up

Required Directory Structure

After downloading, your project directory should look like this:

📁 Your-Project-Directory/
 ┣ 📁 templates/
 ┃  ┃  ┣ 📄 map-template.zip
 ┃  ┃  ┗ 📄 texture-schema.json
 ┃  ┣ � fs25/
 ┃  ┃  ┣ 📄 map-template.zip
 ┃  ┃  ┣ 📄 texture-schema.json
 ┃  ┃  ┣ 📄 tree-schema.json
 ┃  ┃  ┗ 📄 buildings-schema.json
 ┃  ┗ 📄 [additional template files...]
 ┗ 📄 your-python-script.py

Verify Templates

Create a simple test script to verify your setup:

Windows (test_setup.py):

import os
import maps4fs as mfs

# Check if templates directory exists
if os.path.exists("templates"):
    print("✅ Templates directory found")

    # Check for required files
    fs25_template = "templates/fs25/map-template.zip"
    fs25_schema = "templates/fs25/texture-schema.json"

    if os.path.exists(fs25_template):
        print("✅ FS25 map template found")
    else:
        print("❌ FS25 map template missing")

    if os.path.exists(fs25_schema):
        print("✅ FS25 texture schema found")
    else:
        print("❌ FS25 texture schema missing")

    print("🎉 Setup appears to be working!")
else:
    print("❌ Templates directory not found")
    print("Please download the templates folder from the repository")

Run the test:

python test_setup.py

Step 7: Your First Map

Now let's create your first map! Create a new Python file called my_first_map.py:

Complete Beginner Example

import os
import maps4fs as mfs

# Step 1: Choose your game version
print("🎮 Setting up game...")
game = mfs.Game.from_code(game_code)
print(f"✅ Game: {game_code.upper}")

# Step 2: Choose location (latitude, longitude)
# Some example coordinates:
# Paris, France: (48.8566, 2.3522)
# New York, USA: (40.7128, -74.0060)
# Tokyo, Japan: (35.6762, 139.6503)
# Sydney, Australia: (-33.8688, 151.2093)

lat, lon = 48.8566, 2.3522  # Paris, France
coordinates = (lat, lon)
print(f"📍 Location: {lat}, {lon}")

# Step 3: Set map parameters
size = 2048  # Map size in pixels (2048 = 2x2 km map)
rotation = 0  # Map rotation in degrees (0 = no rotation)
print(f"🗺️ Map size: {size}x{size} pixels")

# Step 4: Choose terrain data provider
dtm_provider = mfs.dtm.SRTM30Provider  # Good global coverage
print("🏔️ Using SRTM30 terrain data")

# Step 5: Create output directory
map_directory = "my_first_map"
os.makedirs(map_directory, exist_ok=True)
print(f"📁 Output directory: {map_directory}")

# Step 6: Initialize the map
print("\n🚀 Initializing map generation...")
try:
    mp = mfs.Map(
        game,
        dtm_provider,
        None,  # dtm_provider_settings (None for default)
        coordinates,
        size,
        rotation,
        map_directory,
    )
    print("✅ Map initialized successfully!")
except Exception as e:
    print(f"❌ Error initializing map: {e}")
    print("💡 Make sure you have downloaded the templates folder!")
    exit(1)

# Step 7: Generate the map
print("\n🔄 Starting map generation...")
print("This may take several minutes depending on your computer...")

try:
    component_count = 0
    for component_name in mp.generate:
        component_count += 1
        print(f"[{component_count}/6] Generating {component_name}...")

    print(f"\n🎉 SUCCESS! Map generation completed!")
    print(f"📂 Your map is ready in the '{map_directory}' folder")
    print(f"🎮 You can now copy this folder to your Farming Simulator mods directory")

except Exception as e:
    print(f"\n❌ Error during generation: {e}")
    print("💡 Check the console output above for more details")

Run Your First Map

Save the code above as my_first_map.py and run it:

Windows:

python my_first_map.py

macOS/Linux:

python3 my_first_map.py

Expected Output

You should see output like this:

🎮 Setting up game...
✅ Game: FS25
📍 Location: 48.8566, 2.3522
🗺️ Map size: 2048x2048 pixels
🏔️ Using SRTM30 terrain data
📁 Output directory: my_first_map

🚀 Initializing map generation...
✅ Map initialized successfully!

🔄 Starting map generation...
This may take several minutes depending on your computer...
[1/6] Generating Background...
[2/6] Generating Satellite...
[3/6] Generating Texture...
[4/6] Generating Buildings...
[5/6] Generating Config...
[6/6] Generating Package...

🎉 SUCCESS! Map generation completed!
📂 Your map is ready in the 'my_first_map' folder
🎮 You can now copy this folder to your Farming Simulator mods directory

Advanced Examples

Custom Map Sizes

import maps4fs as mfs

# Different map sizes (larger = more detail, but takes longer)
size_options = {
    "2x2 km": 2048,    # Quick generation, small map
    "4x4 km": 4096,    # Medium generation time, medium map
    "8x8 km": 8192,    # Slow generation, large map
    "16x16 km": 16384  # Very slow generation, huge map
}

# Choose your preferred size
size = size_options["4x4 km"]

Different Terrain Providers

# Global providers (work worldwide)
global_providers = {
    "SRTM30": mfs.dtm.SRTM30Provider,    # 30m resolution, good for most areas
    "ASTER30": mfs.dtm.ASTER30Provider,  # 30m resolution, alternative to SRTM
}

# High-resolution providers (specific regions only)
hires_providers = {
    "Germany": mfs.dtm.GermanyProvider,           # 1m resolution
    "Netherlands": mfs.dtm.NetherlandsProvider,   # 1m resolution
    "USA": mfs.dtm.USGSProvider,                  # 10m resolution
    # Add more as available
}

# Example: Use high-res data for German coordinates
lat, lon = 52.5200, 13.4050  # Berlin, Germany
dtm_provider = hires_providers["Germany"]

Map Rotation

# Rotate your map to align with roads or features
rotation_examples = {
    "No rotation": 0,
    "Slight tilt": 15,
    "Quarter turn": 90,
    "Upside down": 180,
}

rotation = rotation_examples["Slight tilt"]

Multiple Maps Generation

import maps4fs as mfs

# Generate multiple maps from different locations
locations = {
    "Paris": (48.8566, 2.3522),
    "London": (51.5074, -0.1278),
    "Berlin": (52.5200, 13.4050),
    "Rome": (41.9028, 12.4964),
}

game = mfs.Game.from_code("fs25")
dtm_provider = mfs.dtm.SRTM30Provider

for city_name, (lat, lon) in locations.items:
    print(f"\n🌍 Generating map for {city_name}...")

    map_directory = f"map_{city_name.lower}"

    mp = mfs.Map(
        game,
        dtm_provider,
        None,
        (lat, lon),
        2048,  # 2x2 km maps
        0,     # No rotation
        map_directory,
    )

    for component in mp.generate:
        print(f"  Generating {component}...")

    print(f"✅ {city_name} map completed!")

print("\n🎉 All maps generated successfully!")

Example Files & Learning Resources

📝 demo.py - Your Best Starting Point

➡️ Check out the demo.py file in the repository - it's the perfect starting point for learning Maps4FS!

The demo file is a complete, real-world example that includes:

🎯 What's Inside:

Complete map generation workflow from start to finish
Parameter configuration examples with explanations
Progress tracking implementation to see generation status
Error handling examples to deal with common issues
Multiple coordinate examples for different locations
Commented code explaining each step

🚀 How to Use It:

Method 1: Quick Start (PyPI Installation)

# Download just the demo.py file from GitHub
# https://github.com/iwatkot/maps4fs/blob/main/demo.py
# Save it to your project directory and run:
python demo.py

Method 2: Full Source Access (Recommended for Learning)

# Clone the repository to get demo.py and all resources
git clone https://github.com/iwatkot/maps4fs.git
cd maps4fs

# Set up environment (see installation steps above)
# Then simply run:
python demo.py

Method 3: VS Code Development (Best for Experimentation)

# Clone and open in VS Code
git clone https://github.com/iwatkot/maps4fs.git
cd maps4fs
code .

# Open demo.py and press F5 to run with debugger
# Perfect for experimenting and learning!

🔧 Customization Examples:

The demo.py file is designed to be easily modified. Common customizations:

# Change location (edit these lines in demo.py):
lat, lon = 48.8566, 2.3522  # Paris
# To:
lat, lon = 40.7128, -74.0060  # New York

# Change map size:
size = 2048  # 2x2 km
# To:
size = 4096  # 4x4 km

# Change game version:
game_code = "fs25"
# To:

💡 Why Start with demo.py?

Tested & Working: It's guaranteed to work if your environment is set up correctly
Real Example: Shows actual production-ready code, not just snippets
Educational: Learn best practices and proper error handling
Customizable: Easy to modify for your specific needs
Debugging Ready: If using VS Code, you can step through the code line by line

Troubleshooting

Common Installation Issues

❌ "python is not recognized as an internal or external command"

Problem: Python is not installed or not in your PATH.

Solutions:

Windows: Reinstall Python and ensure "Add Python to PATH" is checked
Alternative: Use the full path: C:\Users\YourName\AppData\Local\Programs\Python\Python311\python.exe
Check installation: Open Control Panel → Programs → Look for Python

❌ "pip is not recognized as an internal or external command"

Problem: pip is not installed or not in PATH.

Solutions:

Windows: Try py -m pip install maps4fs instead of pip install maps4fs
Reinstall Python with pip included
Manual pip installation: Download get-pip.py and run python get-pip.py

❌ "Permission denied" or "Access denied" errors

Problem: Insufficient permissions to install packages.

Solutions:

Windows: Run Command Prompt as Administrator
macOS/Linux: Use pip install --user maps4fs to install for current user only
Use virtual environment: (Recommended) Create a virtual environment first

❌ "No module named 'maps4fs'" after installation

Problem: Package installed in wrong Python environment.

Solutions:

Check Python version: Make sure you're using the same Python where you installed maps4fs
Reinstall: pip uninstall maps4fs then pip install maps4fs
Use virtual environment: Create a clean environment for the project

Common Runtime Issues

❌ "FileNotFoundError: Template file not found"

Problem: Missing game templates.

Solutions:

Download templates: Get the templates folder from the Maps4FS repository
Check structure: Ensure templates are in the correct directory structure
Verify files: Run the test_setup.py script from earlier

❌ "ModuleNotFoundError: No module named 'gdal'" or similar

Problem: Missing system dependencies.

Solutions:

Windows:

# Install GDAL and other dependencies
pip install GDAL-3.6.4-cp311-cp311-win_amd64.whl  # Adjust version
# Or use conda
conda install -c conda-forge gdal

macOS:

# Install using Homebrew
brew install gdal
pip install gdal

Linux (Ubuntu/Debian):

# Install GDAL system packages
sudo apt-get install gdal-bin libgdal-dev
pip install gdal

❌ "Memory Error" or system freezing during generation

Problem: Insufficient RAM for map size.

Solutions:

Reduce map size: Start with 2048 (2x2 km) instead of larger sizes
Close other applications: Free up RAM before running
Increase virtual memory: (Windows) Increase page file size
Use SSD storage: HDD will be very slow and may cause timeouts

❌ "HTTP Error" or "Connection failed" during DTM download

Problem: Network issues or provider temporarily unavailable.

Solutions:

Check internet connection: Ensure stable internet access
Try different provider: Switch from SRTM30 to ASTER30 or vice versa
Retry later: Providers may have temporary outages
Use cached data: If you've generated maps before, some data may be cached

❌ Map generation takes forever or gets stuck

Problem: Various causes - insufficient resources, network issues, or corrupted data.

Solutions:

Check console output: Look for specific error messages
Monitor resource usage: Task Manager (Windows) or Activity Monitor (macOS)
Restart generation: Sometimes a fresh start helps
Try smaller area: Test with a smaller map size first

Debugging Steps

Step 1: Verify Basic Setup

# Create debug_setup.py
import sys
import os

print("=== Python Environment Debug ===")
print(f"Python version: {sys.version}")
print(f"Python executable: {sys.executable}")
print(f"Current directory: {os.getcwd}")
print(f"Python path: {sys.path}")

try:
    import maps4fs
    print(f"✅ Maps4FS version: {maps4fs.__version__}")
except ImportError as e:
    print(f"❌ Maps4FS import failed: {e}")

print("\n=== File System Check ===")
if os.path.exists("templates"):
    print("✅ Templates directory found")
    for root, dirs, files in os.walk("templates"):
        level = root.replace("templates", "").count(os.sep)
        indent = " " * 2 * level
        print(f"{indent}{os.path.basename(root)}/")
        subindent = " " * 2 * (level + 1)
        for file in files:
            print(f"{subindent}{file}")
else:
    print("❌ Templates directory not found")

Step 2: Test Minimal Generation

# Create test_minimal.py
import maps4fs as mfs

try:
    print("Testing game initialization...")
    game = mfs.Game.from_code("fs25")
    print("✅ Game initialized")

    print("Testing DTM provider...")
    dtm_provider = mfs.dtm.SRTM30Provider
    print("✅ DTM provider ready")

    print("Testing map initialization...")
    mp = mfs.Map(
        game,
        dtm_provider,
        None,
        (52.0, 8.0),  # Simple coordinates
        1024,         # Very small map for quick test
        0,
        "test_output"
    )
    print("✅ Map initialization successful")
    print("🎉 Basic setup is working!")

except Exception as e:
    print(f"❌ Error: {e}")
    import traceback
    traceback.print_exc

Performance Optimization

For Faster Generation:

Use smaller map sizes for testing (1024 or 2048)
Use SSD storage instead of HDD
Close unnecessary applications to free up RAM
Use local DTM providers when available (faster than downloading)

For Large Maps:

Ensure sufficient RAM (32GB+ for 16x16 km maps)
Use virtual memory/swap as backup
Generate during low-activity hours
Consider cloud computing for very large maps

Getting Help

Before Asking for Help:

Run the debug scripts above and share the output
Include your system information: OS, Python version, RAM, storage type
Describe your exact steps and what went wrong
Share error messages (full text, not just "it doesn't work")

Where to Get Help:

GitHub Issues: https://github.com/iwatkot/maps4fs/issues (recommended)
Include logs: Copy any error messages or console output
Be specific: Mention your OS, Python version, and exact steps you followed

Quick Reference Commands

Windows:

# Check installations
python --version && pip --version && git --version

# Install Maps4FS
pip install maps4fs

# Create and use virtual environment
python -m venv maps4fs-env
maps4fs-env\Scripts\activate
pip install maps4fs

# Run your script
python my_script.py

macOS/Linux:

# Check installations
python3 --version && pip3 --version && git --version

# Install Maps4FS
pip3 install maps4fs

# Create and use virtual environment
python3 -m venv maps4fs-env
source maps4fs-env/bin/activate
pip install maps4fs

# Run your script
python3 my_script.py

PreviousMap Templates NextHow Maps4FS Works

Last updated 21 days ago

hashtagFeatures

hashtagSystem Requirements

hashtagStep 1: Python Installation

hashtagWindows

hashtagmacOS

hashtagLinux

hashtagUbuntu/Debian:

hashtagCentOS/RHEL/Fedora:

hashtagStep 2: Git Installation (Optional, for source installation)

hashtagWindows

hashtagmacOS

hashtagLinux

hashtagStep 3: Check Prerequisites

hashtagWindows Command Prompt or PowerShell:

hashtagmacOS/Linux Terminal:

hashtagStep 4: Create a Project Directory

hashtagWindows:

hashtagmacOS/Linux:

hashtagStep 5: Maps4FS Installation

hashtagOption 1: Install from PyPI (Recommended for Beginners)

hashtagWindows:

hashtagmacOS/Linux:

hashtagOption 2: Install from Source Code (Advanced)

hashtagWindows:

hashtagmacOS/Linux:

hashtag💡 Even Easier: Automated Setup Scripts

hashtag💡 Pro Tip: Using Visual Studio Code

hashtagVirtual Environment (Recommended)

hashtagWindows:

hashtagmacOS/Linux:

hashtagStep 6: Download Required Data Templates

hashtagDownload Method 1: Direct Download (Recommended)

hashtagDownload Method 2: Using Git

hashtagRequired Directory Structure

hashtagVerify Templates

hashtagStep 7: Your First Map

hashtagComplete Beginner Example

hashtagRun Your First Map

hashtagWindows:

hashtagmacOS/Linux:

hashtagExpected Output

hashtagAdvanced Examples

hashtagCustom Map Sizes

hashtagDifferent Terrain Providers

hashtagMap Rotation

hashtagMultiple Maps Generation

hashtagExample Files & Learning Resources

hashtag📝 demo.py - Your Best Starting Point

hashtag🎯 What's Inside:

hashtag🚀 How to Use It:

hashtag🔧 Customization Examples:

hashtag💡 Why Start with demo.py?

hashtagTroubleshooting

hashtagCommon Installation Issues

hashtag❌ "python is not recognized as an internal or external command"

hashtag❌ "pip is not recognized as an internal or external command"

hashtag❌ "Permission denied" or "Access denied" errors

hashtag❌ "No module named 'maps4fs'" after installation

hashtagCommon Runtime Issues

hashtag❌ "FileNotFoundError: Template file not found"

hashtag❌ "ModuleNotFoundError: No module named 'gdal'" or similar

hashtag❌ "Memory Error" or system freezing during generation

hashtag❌ "HTTP Error" or "Connection failed" during DTM download

hashtag❌ Map generation takes forever or gets stuck

hashtagDebugging Steps

hashtagStep 1: Verify Basic Setup

hashtagStep 2: Test Minimal Generation

hashtagPerformance Optimization

hashtagFor Faster Generation:

hashtagFor Large Maps:

hashtagGetting Help

hashtagBefore Asking for Help:

hashtagWhere to Get Help:

hashtagQuick Reference Commands

hashtagWindows:

hashtagmacOS/Linux:

Features

System Requirements

Step 1: Python Installation

Windows

macOS

Linux

Ubuntu/Debian:

CentOS/RHEL/Fedora:

Step 2: Git Installation (Optional, for source installation)

Windows

macOS

Linux

Step 3: Check Prerequisites

Windows Command Prompt or PowerShell:

macOS/Linux Terminal:

Step 4: Create a Project Directory

Windows:

macOS/Linux:

Step 5: Maps4FS Installation

Option 1: Install from PyPI (Recommended for Beginners)

Windows:

macOS/Linux:

Option 2: Install from Source Code (Advanced)

Windows:

macOS/Linux:

💡 Even Easier: Automated Setup Scripts

💡 Pro Tip: Using Visual Studio Code

Virtual Environment (Recommended)

Windows:

macOS/Linux:

Step 6: Download Required Data Templates

Download Method 1: Direct Download (Recommended)

Download Method 2: Using Git

Required Directory Structure

Verify Templates

Step 7: Your First Map

Complete Beginner Example

Run Your First Map

Windows:

macOS/Linux:

Expected Output

Advanced Examples

Custom Map Sizes

Different Terrain Providers

Map Rotation

Multiple Maps Generation

Example Files & Learning Resources

📝 demo.py - Your Best Starting Point

🎯 What's Inside:

🚀 How to Use It:

🔧 Customization Examples:

💡 Why Start with demo.py?

Troubleshooting

Common Installation Issues

❌ "python is not recognized as an internal or external command"

❌ "pip is not recognized as an internal or external command"

❌ "Permission denied" or "Access denied" errors

❌ "No module named 'maps4fs'" after installation

Common Runtime Issues

❌ "FileNotFoundError: Template file not found"

❌ "ModuleNotFoundError: No module named 'gdal'" or similar

❌ "Memory Error" or system freezing during generation

❌ "HTTP Error" or "Connection failed" during DTM download

❌ Map generation takes forever or gets stuck

Debugging Steps

Step 1: Verify Basic Setup

Step 2: Test Minimal Generation

Performance Optimization

For Faster Generation:

For Large Maps:

Getting Help

Before Asking for Help:

Where to Get Help:

Quick Reference Commands

Windows:

macOS/Linux: