Quick Start • Overview • Create a map in 10 steps • How-To-Run
FAQ • Map Structure • Tips and Hints • Modder Toolbox
Supported objects • Generation info • Texture schema • Background terrain • Overview image
DDS conversion • Advanced settings • Resources • Bugs and feature requests
Special thanks

🗺️ Supports 2x2, 4x4, 8x8, 16x16 and any custom size maps
🔄 Support map rotation 🆕
🌾 Automatically generates fields 🆕
🌽 Automatically generates farmlands 🆕
🌿 Automatically generates decorative foliage 🆕
🌲 Automatically generates forests 🆕
🌍 Based on real-world data from OpenStreetMap
🏞️ Generates height map using SRTM dataset
📦 Provides a ready-to-use map template for the Giants Editor
🚜 Supports Farming Simulator 22 and 25
🔷 Generates *.obj files for background terrain based on the real-world height map
📄 Generates scripts to download high-resolution satellite images from QGIS in one click
📕 Detailed documentation and tutorials
🧰 Modder Toolbox to help you with various tasks

🌎 Detailed terrain based on real-world data.


🛰️ Realistic background terrain with satellite images.


📐 Perfectly aligned background terrain.


🌿 Automatically generates decorative foliage.


🌲 Automatically generates forests.


🗒️ True-to-life blueprints for fast and precise modding.


🌾 Field generation with one click.


🌽 Automatic farmlands generation based on the fields.

📹 A complete step-by-step video tutorial is here!

How to Generate a Map for Farming Simulator 25 and 22 from a real place using maps4FS.

Quick Start

There are several ways to use the tool. You obviously need the first one, but you can choose any of the others depending on your needs.

🚜 For most users

Option 1: Open the maps4fs on StreamLit and generate a map template in a few clicks.
Note, that StreamLit community hosting has some limitations, such as:

1. Maximum map size is 4096x4096 meters.
   
2. Advanced settings are disabled.
   
3. Texture dissolving is disabled (they will look worse).
   

If you run the application locally, you won't have any of these limitations and will be able to generate maps of any size with any settings you want and nice looking textures.
So, jump to Docker version to launch the tool with one command and get the full experience.

😎 For advanced users

Option 2: Run the Docker version in your browser. Launch the following command in your terminal:

docker run -d -p 8501:8501 --name maps4fs iwatkot/maps4fs

And open http://localhost:8501 in your browser.
If you don't know how to use Docker, navigate to the Docker version, it's really simple.

🤯 For developers

Option 3: Python package. Install the package using the following command:

pip install maps4fs

And refer to the Python package section to learn how to use it.

Overview

The core idea is coming from the awesome maps4cim project.

The main goal of this project is to generate map templates, based on real-world data, for the Farming Simulator. It's important to mention that templates are not maps. They are just a starting point for creating a map. This tool just uses built-in textures to highlight different types of terrain and buildings with correct shapes and scales and to generate a height map. The rest of the work is up to you. So if you thought that you could just run this tool and get a playable map, then I'm sorry to disappoint you. But if you are a map maker, then this tool will save you a lot of time.
So, if you're new to map making, here's a quick overview of the process:

1. Generate a map template using this tool.
2. Download the Giants Editor.
3. Open the map template in the Giants Editor.
4. Now you can start creating your map (adding roads, fields, buildings, etc.).

Previews

The generator also creates multiple previews of the map. Here's the list of them:

1. General preview - merging all the layers into one image with different colors.
2. Grayscale DEM preview - a grayscale image of the height map (as it is).
3. Colored DEM preview - a colored image of the height map (from blue to red). The blue color represents the lowest point, and the red color represents the highest point.

Preview of a 16 km map with a 500-meter mountain in the middle of it.

Parameters:

• coordinates: 45.15, 19.71
• size: 16 x 16 km

Step by step

Don't know where to start? Don't worry, just follow this step-by-step guide to create your first map in 10 simple steps.

How-To-Run

Option 1: StreamLit

🟢 Recommended for all users. 🛠️ Don't need to install anything.
🗺️ Supported map sizes: 2x2, 4x4 km.
⚙️ Advanced settings: disabled.
🖼️ Texture dissolving: disabled.
Using the StreamLit version of the tool is the easiest way to generate a map template. Just open the link and follow the instructions. Note: due to CPU and RAM limitations of the hosting, the generation may take some time. If you need faster processing, use the Docker version.

Using it is easy and doesn't require any guides. Enjoy!

Option 2: Docker version

🟠 Recommended for users who want bigger maps, fast generation, nice-looking textures, and advanced settings.
🛠️ Launch with one single command.
🗺️ Supported map sizes: 2x2, 4x4, 8x8, 16x16 km and any custom size.
⚙️ Advanced settings: enabled.
🖼️ Texture dissolving: enabled.
You can launch the project with minimalistic UI in your browser using Docker. Follow these steps:

1. Install Docker for your OS.
2. Run the following command in your terminal:

docker run -d -p 8501:8501 --name maps4fs iwatkot/maps4fs

3. Open your browser and go to http://localhost:8501.
4. Fill in the required fields and click on the Generate button.
5. When the map is generated click on the Download button to get the map.

Option 3: Python package

🔴 Recommended for developers.
🗺️ Supported map sizes: 2x2, 4x4, 8x8, 16x16 km and any custom size.
⚙️ Advanced settings: enabled.
🖼️ Texture dissolving: enabled.
You can use the Python package to generate maps. Follow these steps:

1. Install the package from PyPI:

pip install maps4fs

2. Import the Game class and create an instance of it:

import maps4fs as mfs

game = mfs.Game.from_code("FS25")

In this case, the library will use the default templates, which should be present in the data directory, which should be placed in the current working directory.
Structure example:

📁 data
 ┣ 📄 fs22-map-template.zip
 ┗ 📄 fs22-texture-schema.json

So it's recommended to download the data directory from the repository and place it in the root of your project.

3. Create an instance of the Map class:

import maps4fs as mfs

map = mfs.Map(
  game,
  (52.5200, 13.4050),  # Latitude and longitude of the map center.
  height=1024,  # The height of the map in meters.
  width=1024,  # The width of the map in meters.
  map_directory="path/to/your/map/directory",  # The directory where the map will be saved.
)

4. Generate the map: The generate method returns a generator, which yields the active component of the map. You can use it to track the progress of the generation process.

for active_component in map.generate():
    print(active_component)

The map will be saved in the map_directory directory.

Modder Toolbox

The tool now has a Modder Toolbox, which is a set of tools to help you with various tasks. You can open the toolbox by switching to the 🧰 Modder Toolbox tab in the StreamLit app.

Tool Categories

Tools are divided into categories, which are listed below.

For Textures and DEM

• GeoTIFF windowing - allows you to upload your GeoTIFF file and select the region of interest to extract it from the image. It's useful when you have high-resolution DEM data and want to create a height map using it.

For Background terrain

• Convert image to obj model - allows you to convert the image to the obj model. You can use this tool to create the background terrain for your map. It can be extremely useful if you have access to the sources of high-resolution DEM data and want to create the background terrain using it.

Supported objects

The project is based on the OpenStreetMap data. So, refer to this page to understand the list below.

• "building": True
• "highway": ["motorway", "trunk", "primary"]
• "highway": ["secondary", "tertiary", "road", "service"]
• "highway": ["unclassified", "residential", "track"]
• "natural": ["grassland", "scrub"]
• "landuse": "farmland"
• "natural": ["water"]
• "waterway": True
• "natural": ["wood", "tree_row"]
• "railway": True

The list will be updated as the project develops.

Generation info

The script will generate the generation_info.json file in the output folder. It is split into different sections, which represent the components of the map generator. You may need this information to use some other tools and services to obtain additional data for your map.

List of components:

• Config - this component handles the map.xml file, where the basic description of the map is stored.
• Texture - this component describes the textures, that were used to generate the map.
• DEM - this component describes the Digital Elevation Model (the one which creates terrain on your map), which was used to generate the height map and related to the dem.png file.
• I3d - this component describes the i3d file, where some specific attributes properties, and paths to the files are stored.
• Background - this component describes the 8 tiles, that surround the map.

Below you'll find descriptions of the components and the fields that they contain.
ℹ️ If there's no information about the component, it means that at the moment it does not store any data in the generation_info.json file.

Config

Example of the Config component:

"Config": {
    "Overview": {
        "epsg3857_string": "2249906.6679576184,2255734.9033189337,5663700.389039194,5669528.6247056825 [EPSG:3857]",
        "south": 45.304132173367165,
        "west": 45.267296012425376,
        "north": 20.263611405732693,
        "east": 20.211255476687537,
        "height": 4096,
        "width": 4096
    }
},

The Overview section contains information to create an overview image, which represents the in-game map. You can use the epsg3857_string to obtain the satellite images in the QGIS. So this section describes the region of the map plus the borders. Usually, it's exactly 2X the size of the map.
And here's the list of the fields:

• "epsg3857_string" - the string representation of the bounding box in the EPSG:3857 projection, it is required to obtain the satellite images in the QGIS,
  
• "south" - the southern border of overview region,
  
• "west" - the western border of overview region,
  
• "north" - the northern border of overview region,
  
• "east" - the eastern border of overview region,
  
• "height" - the height of the overview region in meters (2X the size of the map),
  
• "width" - the width of the overview region in meters,
  

Texture

Example of the Texture component:

"Texture": {
    "coordinates": [
        45.28571409289627,
        20.237433441210115
    ],
    "bbox": [
        45.29492313313172,
        45.27650505266082,
        20.250522423471406,
        20.224344458948824
    ],
    "map_height": 2048,
    "map_width": 2048,
    "minimum_x": 439161.2439774908,
    "minimum_y": 5013940.540089059,
    "maximum_x": 441233.5397821935,
    "maximum_y": 5016006.074349126,
},

And here's the list of the fields:

• "coordinates" - the coordinates of the map center which you entered,
  
• "bbox" - the bounding box of the map in lat and lon,
  
• "map_height" - the height of the map in meters (this one is from the user input, e.g. 2048 and so on),
  
• "map_width" - the width of the map in meters (same as above),
  
• "minimum_x" - the minimum x coordinate of the map (UTM projection),
  
• "minimum_y" - the minimum y coordinate of the map (UTM projection),
  
• "maximum_x" - the maximum x coordinate of the map (UTM projection),
  
• "maximum_y" - the maximum y coordinate of the map (UTM projection),

Background

The background component consists of the 8 tiles, each one representing the tile, that surrounds the map. The tiles are named as the cardinal points, e.g. "N", "NE", "E" and so on.
Example of the Background component:

"Background": {
"N": {
    "center_latitude": 45.30414170952092,
    "center_longitude": 20.237433441210115,
    "epsg3857_string": "2251363.25324853,2254278.318028022,5668072.719985372,5670987.784803056 [EPSG:3857]",
    "height": 2048,
    "width": 2048,
    "north": 45.31335074975637,
    "south": 45.29493266928547,
    "east": 20.250526677438195,
    "west": 20.224340204982035
},
}

And here's the list of the fields:

• "center_latitude" - the latitude of the center of the tile,
  
• "center_longitude" - the longitude of the center of the tile,
  
• "epsg3857_string" - the string representation of the bounding box in the EPSG:3857 projection, it is required to obtain the satellite images in the QGIS,
  
• "height" - the height of the tile in meters,
  
• "width" - the width of the tile in meters,
  
• "north" - the northern border of the tile,
  
• "south" - the southern border of the tile,
  
• "east" - the eastern border of the tile,
  
• "west" - the western border of the tile,
  

Texture schema

maps4fs uses a simple JSON file to define the texture schema. For each ofthe supported games, this file has unique entries, but the structure is the same. Here's an example of the schema for Farming Simulator 25:

[
    {
    "name": "forestRockRoots",
    "count": 2,
    "exclude_weight": true
  },
  {
    "name": "grass",
    "count": 2,
    "tags": { "natural": "grassland" },
    "color": [34, 255, 34],
    "priority": 0
  },
  {
    "name": "grassClovers",
    "count": 2
  },
  {
    "name": "grassCut",
    "count": 2
  },
  {
    "name": "grassDirtPatchy",
    "count": 2,
    "tags": { "natural": ["wood", "tree_row"] },
    "width": 2,
    "color": [0, 252, 124]
  }
]

Let's have a closer look at the fields:

• name - the name of the texture. Just the way the file will be named.
• count - the number of textures of this type. For example, for the dirtMedium texture there will be two textures: dirtMedium01_weight.png and dirtMedium02_weight.png. ℹ️ There's one texture that has count 0, it's the waterPuddle texture from FS22, which is not present in FS25.
• tags - the tags from the OpenStreetMap data. Refer to the section Supported objects to see the list of supported tags. If there are no tags, the texture file will be generated empty and no objects will be placed on it.
• width - the width of the texture in meters. Some of the objects from OSM (roads, for example) are lines, not areas. So, to draw them correctly, the tool needs to know the width of the line.
• color - the color of the texture. It's used only in the preview images and has no effect on the map itself. But remember that previews are crucial for the map-making process, so it's better to set the color to something that represents the texture.
• priority - the priority of the texture for overlapping. Textures with higher priorities will be drawn over the textures with lower priorities. ℹ️ The texture with 0 priority considers the base layer, which means that all empty areas will be filled with this texture.
• exclude_weight - this is only used for the forestRockRoots texture from FS25. It just means that this texture has no weight postfix, that's all.

Background terrain

The tool now supports the generation of the background terrain. If you don't know what it is, here's a brief explanation. The background terrain is the world around the map. It's important to create it because if you don't, the map will look like it's floating in the void. The background terrain is a simple plane that can (and should) be textured to look fine.
So, the tool generates the background terrain in the form of the 8 tiles, which surround the map. The tiles are named as the cardinal points, e.g. "N", "NE", "E" and so on. All those tiles will be saved in the background directory with corresponding names: N.obj, NE.obj, E.obj, and so on.
If you don't want to work with separate tiles, the tool also generates the FULL.obj file, which includes everything around the map and the map itself. It may be a convenient approach to work with one file, one texture, and then just cut the map from it.

➡️ No matter which approach you choose, you still need to adjust the background terrain to connect it to the map without any gaps. But with a single file, it's much easier to do.

If you're willing to create a background terrain, you will need Blender, the Blender Exporter Plugins, and the QGIS. You'll find the download links in the Resources section.

If you're afraid of this task, please don't be. It's really simple and I've prepared detailed step-by-step instructions for you, you'll find them in the separate README files. Here are the steps you need to follow:

1. Download high-resolution satellite images.
2. Prepare the i3d files.
3. Import the i3d files to Giants Editor.

Overview image

The overview image is an image that is used as an in-game map. No matter what the size of the map, this file is always 4096x4096 pixels, while the region of your map is 2048x2048 pixels in the center of this file. The rest of the image is just here for a nice view, but you still may add satellite pictures to this region.

Cool image by @ZenJakey.

So, in the same way, you've downloaded the satellite images for the background terrain, you can download them for the overview image. Just use the epsg3857_string from the generation_info.json file. You'll find the needed string in the Config component in the Overview section:

"Config": {
    "Overview": {
        "epsg3857_string": "2249906.6679576184,2255734.9033189337,5663700.389039194,5669528.6247056825 [EPSG:3857]",
    }
},

After that, you need to resize the image to 4096x4096 pixels and convert it to the .dds format.

DDS conversion

The .dds format is the format used in the Farming Simulator for the textures, icons, overview, and preview images. There a plenty of options to convert the images to the .dds format, you can just google something like png to dds, and the first link probably will help you with it.

List of the important DDS files:

• icon.dds - 256x256 pixels, the icon of the map,
• preview.dds - 2048x2048 pixels, the preview image of the map on the loading screen,
• mapsUS/overview.dds - 4096x4096 pixels, the overview image of the map (in-game map)

Advanced settings

The tool supports the custom size of the map. To use this feature select Custom in the Map size dropdown and enter the desired size. The tool will generate a map with the size you entered.

⛔️ Do not use this feature, if you don't know what you're doing. In most cases, the Giants Editor will just crash on opening the file, because you need to enter specific values for the map size.

You can also apply some advanced settings to the map generation process. Note that they're ADVANCED, so you don't need to use them if you're not sure what they do.

DEM Advanced settings

• Multiplier: the height of the map is multiplied by this value. So the DEM map is just a 16-bit grayscale image, which means that the maximum available value there is 65535, while the actual difference between the deepest and the highest point on Earth is about 20 km. Just note that this setting mostly does not matter, because you can always adjust it in the Giants Editor, learn more about the DEM file and the heightScale parameter in docs. By default, it's set to 1.

• Blur radius: the radius of the Gaussian blur filter applied to the DEM map. By default, it's set to 21. This filter just makes the DEM map smoother, so the height transitions will be more natural. You can set it to 1 to disable the filter, but it will result in a Minecraft-like map.

• Plateau height: this value will be added to each pixel of the DEM image, making it "higher". It's useful when you want to add some negative heights on the map, that appear to be in a "low" place. By default, it's set to 0.

Texture Advanced settings

• Fields padding - this value (in meters) will be applied to each field, making it smaller. It's useful when the fields are too close to each other and you want to make them smaller. By default, it's set to 0.

Farmlands Advanced settings

• Farmlands margin - this value (in meters) will be applied to each farmland, making it bigger. You can use the value to adjust how much the farmland should be bigger than the actual field. By default, it's set to 3.

Vegetation Advanced settings

• Forest density - the density of the forest in meters. The lower the value, the lower the distance between the trees, which makes the forest denser. Note, that low values will lead to enormous number of trees, which may cause the Giants Editor to crash or lead to performance issues. By default, it's set to 10.

• Random plants - when adding decorative foliage, enabling this option will add different species of plants to the map. If unchecked only basic grass (smallDenseMix) will be added. Defaults to True.

Resources

In this section, you'll find a list of the resources that you need to create a map for the Farming Simulator.
To create a basic map, you only need the Giants Editor. But if you want to create a background terrain - the world around the map, so it won't look like it's floating in the void - you also need Blender and the Blender Exporter Plugins. To create realistic textures for the background terrain, the QGIS is required to obtain high-resolution satellite images.

1. Giants Editor - the official tool for creating maps for the Farming Simulator.
2. Blender - the open-source 3D modeling software that you can use to create models for the Farming Simulator.
3. Blender Exporter Plugins - the official plugins for exporting models from Blender to i3d format (the format used in the Farming Simulator).
4. QGIS - the open-source GIS software that you can use to obtain high-resolution satellite images for your map.
5. CompressPngCom - the online tool to compress the PNG images. May be useful to reduce the size of the satellite images.
6. AnyConv - the online tool to convert the PNG images to the DDS format. You'll need this format for the textures, icons, overview, and preview images.

Bugs and feature requests

➡️ Please, before creating an issue or asking some questions, check the FAQ section.
If you find a bug or have an idea for a new feature, please create an issue here or contact me directly on Telegram or on Discord: iwatkot.

Special thanks

Of course, first of all, thanks to the direct contributors of the project.

But also, I want to thank the people who helped me with the project in some way, even if they didn't contribute directly. Here's the list of them:

• Ka5tis - for investigating the issue with a "spiky terrain" and finding a solution - changing the DisplacementLayer size to a higher value.
• Kalderone - for useful feedback, suggestions, expert advice on the map-making process and highlihting some important settings in the Giants Editor.
• OneSunnySunday - for expert advice on Blender, help in processing background terrain, and compiling detailed tutorials on how to prepare the OBJ files for use in Giants Editor.