maps4fs 0.7.0

Generate map templates for Farming Simulator from real places.

Quick Start • Overview • How-To-Run • Features • Supported objects • Settings • Bugs and feature requests

Supported Games

✅ Farming Simulator 22
🔃 Farming Simulator 25 (changes in the library are ready, waiting for the Giants to release the Giants Editor v10)

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.

😎 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 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 a 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.

So the colored DEM preview can be very handy when you're trying to find the best value for the max_height parameter. Learn more about it in the Settings section.

In the second row of the image you can see the following images:

1. DEM preview with max_height=200.
2. Colored DEM preview with max_height=200.
3. Colored DEM preview with max_height=50.

As you can see there's a huge difference between images 2 and 3. The third (with lower max_height) will have a higher terrain contrast, and the second one will have lower differences between the terrain heights.
There's no like "in real world" option, because FS system of coordinates does not work in meters or something like that when talking about DEM. So you need to experiment with the max_height parameter to get the desired result. To clarify: in the example above the difference on the platue is about 80 meters, so max_height=50 made this like super mountainous terrain, and max_height=200 made it like a plain.

How-To-Run

You'll find detailed instructions on how to run the project below. But if you prefer video tutorials, here's one for you: Video tutorial: How to generate a Farming Simulator 22 map from real-world data.

Option 1: StreamLit

🗺️ Supported map sizes: 2x2, 4x4, 8x8, 16x16 km.
🟢 Recommended for all users, you don't need to install anything.
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

🗺️ Supported map sizes: 2x2, 4x4, 8x8, 16x16 km.
🟠 Recommended for users who want faster processing, very simple installation.
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 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

🗺️ Supported map sizes: 2x2, 4x4, 8x8, 16x16 km (and ANY other you may add).
🔴 Recommended for developers.
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.
  distance=1024,  # The DISTANCE from the center to the edge of the map in meters. The map will be 2048x2048 meters.
  map_directory="path/to/your/map/directory",  # The directory where the map will be saved.
  blur_seed=5,  # The seed for the blur algorithm. The default value is 5, which means 5 meters.
  max_height=400  # The maximum height of the map.
)

4. Generate the map:

map.generate()

The map will be saved in the map_directory directory.

Settings

Advanced settings are available in the tool's UI under the Advanced Settings tab. Here's the list of them:

• max_height - the maximum height of the map. The default value is 400. Select smaller values for plain-like maps and bigger values for mountainous maps. You may need to experiment with this value to get the desired result.
• blur_seed - the seed for the blur algorithm. The default value is 5, which means 5 meters. The bigger the value, the smoother the map will be. The smaller the value, the more detailed the map will be. Keep in mind that for some regions, where terrain is bumpy, disabling the blur algorithm may lead to a very rough map. So, I recommend leaving this value as it is.

Features

• Allows to enter a location by lat and lon (e.g. from Google Maps).
• Allows to select a size of the map (2x2, 4x4, 8x8 km, 16x16 km).
• Generates a map template (check the list of supported objects in this section).
• Generates a height map.

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"]
• "highway": ["unclassified", "residential", "track"]
• "natural": "grassland"
• "landuse": "farmland"
• "natural": ["water"]
• "waterway": True
• "natural": ["wood", "tree_row"]

The list will be updated as the project develops.

Info sequence

The script will also generate the generation_info.json file in the output folder. It contains the following keys:
"coordinates" - the coordinates of the map center which you entered,
"bbox" - the bounding box of the map in lat and lon,
"distance" - the size of the map in meters,
"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),
"height" - the height of the map in meters (it won't be equal to the distance since the Earth is not flat, sorry flat-earthers),
"width" - the width of the map in meters,
"height_coef" - since we need a texture of exact size, the height of the map is multiplied by this coefficient,
"width_coef" - same as above but for the width,
"tile_name" - the name of the SRTM tile which was used to generate the height map, e.g. "N52E013"

You can use this information to adjust some other sources of data to the map, e.g. textures, height maps, etc.

Bugs and feature requests

If you find a bug or have an idea for a new feature, please create an issue here or contact me directly on Telegram.