Modder Toolbox, Knowledge base, FAQ

* Toolbox WIP.

* WebUI refactoring.

* GeoTIFF windowing tool.

* Minor code fixes.

* README update.

.streamlit/config.toml

@@ -0,0 +1,4 @@
+# .streamlit/config.toml
+
+[server]
+maxUploadSize = 500

.vscode/tasks.json

@@ -4,7 +4,7 @@
         {
             "label": "Run Streamlit",
             "type": "shell",
-            "command": "streamlit run webui/webui.py",
+            "command": "streamlit run webui/main.py",
             "group": "build",
             "presentation": {
                 "reveal": "always",

README.md

@@ -7,7 +7,8 @@
   <a href="#Quick-Start">Quick Start</a> •
   <a href="#Overview">Overview</a> • 
   <a href="#How-To-Run">How-To-Run</a> •
-  <a href="tutorials/FAQ.md">FAQ</a><br>
+  <a href="docs/FAQ.md">FAQ</a> •
+  <a href="#Modder-Toolbox">Modder Toolbox</a><br>
   <a href="#Supported-objects">Supported objects</a> •
   <a href="#Generation-info">Generation info</a> •
   <a href="#Texture-schema">Texture schema</a> •
@@ -41,6 +42,7 @@
 🚜 Supports Farming Simulator 22 and 25<br>
 🔷 Generates *.obj files for background terrain based on the real-world height map<br>
 📄 Generates scripts to download high-resolution satellite images from [QGIS](https://qgis.org/download/) in one click<br>
+🧰 Modder Toolbox to help you with various of tasks 🆕<br>
 
 <p align="center">
 <img src="https://github.com/user-attachments/assets/cf8f5752-9c69-4018-bead-290f59ba6976"><br>
@@ -172,6 +174,16 @@ for active_component in map.generate():
 
 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.<br>
+
+![Modder Toolbox](https://github.com/user-attachments/assets/18f169e9-1a5b-474c-b488-6becfffadcea)
+
+### Tool categories
+Tools are divided into categories, which are listed below.
+#### Textures and DEM
+- **GeoTIFF windowing** - allows you to upload your GeoTIFF file and select the region of interest to extract it from the image.
+
 ## Supported objects
 The project is based on the [OpenStreetMap](https://www.openstreetmap.org/) data. So, refer to [this page](https://wiki.openstreetmap.org/wiki/Map_Features) to understand the list below.
 - "building": True
@@ -350,9 +362,9 @@ If you're willing to create a background terrain, you will need: Blender, the Bl
 
 If you're afraid of this task, please don't be. It's really simple and I've prepaired 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](tutorials/README_satellite_images.md).
-2. [Prepare the i3d files](tutorials/README_i3d.md).
-3. [Import the i3d files to Giants Editor](tutorials/README_giants_editor.md).
+1. [Download high-resolution satellite images](docs/download_satellite_images.md).
+2. [Prepare the i3d files](docs/create_background_terrain.md).
+3. [Import the i3d files to Giants Editor](docs/import_to_giants_editor.md).
 
 ## Overview image
 The overview image is an image that is used as 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 center of this file. The rest of the image is just here for nice view, but you still may add satellite pictures to this region.<br>
@@ -392,7 +404,7 @@ You can also apply some advanced settings to the map generation process. Note th
 
 Here's the list of the advanced settings:
 
-- DEM 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 avaiable value there is 65535, while the actual difference between the deepest and the highest point on Earth is about 20 km. So, by default this value is set to 3. Just note that this setting mostly does not matter, because you can always adjust it in the Giants Editor, learn more about the [heightScale](https://www.farming-simulator.org/19/terrain-heightscale.php) parameter on the [PMC Farming Simulator](https://www.farming-simulator.org/) website.
+- DEM 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 avaiable 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 paramter in [docs](docs/dem.md). By default, it's set to 1.
 
 - DEM 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 as a Minecraft-like map.
 
@@ -410,5 +422,5 @@ To create a basic map, you only need the Giants Editor. But if you want to creat
 6. [AnyConv](https://anyconv.com/png-to-dds-converter/) - 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](tutorials/FAQ.md) section.<br>
+➡️ Please, before creating an issue or asking some questions, check the [FAQ](docs/FAQ.md) section.<br>
 If you find a bug or have an idea for a new feature, please create an issue [here](https://github.com/iwatkot/maps4fs/issues) or contact me directly on [Telegram](https://t.me/iwatkot) or on Discord: `iwatkot`.

tutorials/FAQ.md → docs/FAQ.md

@@ -8,13 +8,25 @@ First of all, you need to understand, that the project uses the data from the [O
 
 ### I can see the object on OSM, but it doesn't appear on the map, why?
 
-The `maps4fs` tool DOES NOT add everything from OSM to the map. Instead of projecting everything, it works with a whitelist of objects that are allowed to be displayed. And you, actually, can check this list in the [Supported Objects](../README.md#supported-objects) section of the main README file.<br>
-➡️ It's really easy to add a new object to the whitelist, so if you think that something should be displayed, contact me in [Discord](https://discord.gg/Sj5QKKyE42) or open an issue on GitHub. I will check the object and add it to the whitelist if it's correct.
+The `maps4fs` tool DOES NOT add everything from OSM to the map. Instead of projecting everything, it works with a whitelist of objects that are allowed to be displayed. And you, actually, can check this list in the [Supported Objects](../README.md#supported-objects) section of the main README file.  
+It's really easy to add a new object to the whitelist, so if you think that something should be displayed, contact me in [Discord](https://discord.gg/Sj5QKKyE42) or open an issue on GitHub. I will check the object and add it to the whitelist if it's correct.
 
 ### There's no needed objects on OSM, what should I do?
 
-The good news is that you can add them by yourself! The OpenStreetMap project is open for everyone, and you can add any object you want. Just go to the [OpenStreetMap](https://www.openstreetmap.org/) website, create an account, and start mapping. Ensure, that you're adding the correct objects with corresponding tags, and they will appear on the map, usually it taskes from 5 to 30 minutes.<br>
-➡️ Please, while editing OSM, follow the [OSM Wiki](https://wiki.openstreetmap.org/wiki/Main_Page) and the [OSM Tags](https://wiki.openstreetmap.org/wiki/Map_Features) to add the correct objects. And also, respect the [OSM Guidelines](https://wiki.openstreetmap.org/wiki/Good_practice) and the community of this incredible project. Don't mess up with the data, and don't add anything that doesn't exist in the real world. It's just not cool.
+The good news is that you can add them by yourself! The OpenStreetMap project is open for everyone, and you can add any object you want. Just go to the [OpenStreetMap](https://www.openstreetmap.org/) website, create an account, and start mapping. Ensure, that you're adding the correct objects with corresponding tags, and they will appear on the map, usually it taskes from 5 to 30 minutes.  
+Please, while editing OSM, follow the [OSM Wiki](https://wiki.openstreetmap.org/wiki/Main_Page) and the [OSM Tags](https://wiki.openstreetmap.org/wiki/Map_Features) to add the correct objects. And also, respect the [OSM Guidelines](https://wiki.openstreetmap.org/wiki/Good_practice) and the community of this incredible project. Don't mess up with the data, and don't add anything that doesn't exist in the real world. It's just not cool.
+
+### How can I download satellite images for the map?
+
+You can find the detailed tutorial [here](https://github.com/iwatkot/maps4fs/blob/main/docs/download_satellite_images.md).
+
+### How can I texture object and export it in the *.i3d format?
+
+You can find the detailed tutorial [here](https://github.com/iwatkot/maps4fs/blob/main/docs/create_background_terrain.md).
+
+### How can I import the *.i3d file to the map?
+
+You can find the detailed tutorial [here](https://github.com/iwatkot/maps4fs/blob/main/docs/import_to_giants_editor.md).
 
 
 If you think that some question should be added here, please, contact me in [Discord](https://discord.gg/Sj5QKKyE42) or open an issue on GitHub. Thank you! 

tutorials/README_i3d.md → docs/create_background_terrain.md

@@ -1,8 +1,8 @@
 ## How to create a background terrain
 
-To create a background terrain for the Farming Simulator map, you need to open the `*.obj` files with the terrain, obtain the satellite images as described in the [Download high-resolution satellite images](README_satellite_images.md) tutorial to use them as textures and export your results to the `*.i3d` format.<br>
+To create a background terrain for the Farming Simulator map, you need to open the `*.obj` files with the terrain, obtain the satellite images as described in the [Download high-resolution satellite images](download_satellite_images.md) tutorial to use them as textures and export your results to the `*.i3d` format.<br>
 
-ℹ️ In this tutorials it's assumed that you have already generated the map and downloaded satellite images from the previous step: [Download high-resolution satellite images](README_satellite_images.md).<br>
+ℹ️ In this tutorials it's assumed that you have already generated the map and downloaded satellite images from the previous step: [Download high-resolution satellite images](download_satellite_images.md).<br>
 
 Let's go straight to the deal:
 
@@ -78,4 +78,4 @@ Now ensure that the object is selected [1], specify the path to the output file
 
 ![Export to i3d](https://github.com/user-attachments/assets/ad3913d7-a16e-47c0-a039-9f792e34ad4c)
 
-Now we can go to the final section of the tutorial: [Import the i3d files to Giants Editor](README_giants_editor.md). Or you can go back to the previous step: [Download high-resolution satellite images](README_satellite_images.md).
+Now we can go to the final section of the tutorial: [Import the i3d files to Giants Editor](import_to_giants_editor.md). Or you can go back to the previous step: [Download high-resolution satellite images](download_satellite_images.md).

docs/dem.md

@@ -0,0 +1,17 @@
+## Digital Elevation Models (DEM)
+DEM is used in Farming Simulator maps to define the terrain height.  
+Every hill, valley, and slope is defined by a DEM. While it may sounds complex, it's really just a 2D grid where each cell has a height value.
+### File description
+**Image size:** FS25 -> (map height + 1, map width + 1) FS22 -> (map height / 2 + 1, map width / 2 + 1)  
+**Channels:** 1  
+**Data Type:** uint16  (unsigned 16-bit integer)  
+**File Format:** .png  
+**File Path:** FS25 -> `map_directory/data/dem.png` FS22 -> `map_directory/data/map_dem.png`  
+DEM image is a single channel unsigned 16-bit integer image, which means that each pixel can have an integer value between 0 and 2^16 (65535). So, if the image can have values from 0 to 65535, while the highest point on Earth is 8848 meters, how does it work?
+### Height scale
+And this, where the **heightScale** parameter comes in. It's a multiplier that converts the pixel value to it's in-game height.  By default, in Giants maps, it's value set to 255, but if you're working with DEMs, which contains real-world height values, you should make it much higher. The selection of the actual value is up to you, you can play around with it to get the best result.  
+To set this value, you need to open the map.i3d file in Giants Editor, select the terrain on the **Scenegraph** tab, choose **Terrain** tab in the **Attributes** window, and set the **heightScale** parameter. After it you usually need to save the file and reload the map (**File** -> **Reload**).
+### Units per pixel
+In Farming Simulator 25 the size of the DEM image is usually the same as the map size but with an additional pixel in each dimension. For example, if the map size is 2048x2048, the DEM image size will be 2049x2049. But in Farming Simulator 22 the DEM image size is half of the map size. So, if the map size is 2048x2048, the DEM image size will be 1025x1025.  
+But actually, it can be changed using the **unitsPerPixel** parameter in the map.i3d file. It defines how many in-game units (meters) each pixel of the DEM image represents. So, in the FS25 by default, it's set to 1, which means that each pixel of the DEM image represents 1 meter in the game. But in FS22 it's set to 2, and that's why the DEM image size is half of the map size.  
+To set this value, you need to open the map.i3d file in Giants Editor, select the terrain on the **Scenegraph** tab, choose **Terrain** tab in the **Attributes** window, and set the **unitsPerPixel** parameter. Just a reminder, it should be an integer value. After it you usually need to save the file and reload the map (**File** -> **Reload**).

tutorials/README_satellite_images.md → docs/download_satellite_images.md

@@ -103,6 +103,20 @@ layers = [
 ```
 As a result of saving those `.tif` files, you'll get one image with the exact bounds and another one with the margin around it. In case you want manually adjust the bounds, you can use the image with the margin.
 
+### Approach 1: Using maps4fs Toolbox: GeoTIFF windowing
+
+It's a recommended approach.
+
+2. Navigate to the `🧰 Modder Toolbox` -> `🖼️ Textures and DEM` -> `🪟 GeoTIFF windowing` and upload your tiff image (with margin).
+
+3. Enter coordinates of the center point of the map. It's recommended to paste it EXACTLY the same as in the `generation_info.json` and the size of the map (2048, 4096 and so on). Click on the `Extract ROI` button.
+
+![GeoTIFF windowing](https://github.com/user-attachments/assets/2e63345b-58b1-4d06-8c87-0f7e655a6413)
+
+4. Now you can download windowed image, that will be almost perfectly aligned with the map. But if you want to make it perfectly aligned, you can continue with the second approach.
+
+### Approach 2: Manual adjustment in image editor
+
 2. Create a new image in Photoshop or any other image editor, which allows working with layers, put some of your texture files in center of it. For example for map of size 4096 x 4096 pixels, you need to create an image of size 8192 x 8192 pixels, and you need to put the texture in the center of it.
 
 3. Now add there your satellite images with margins, lower the opacity of this layer and try to manually adjust it. Please note, that Earth is not flat, so it WONT be just scale and move, you also need to rotate it a bit and maybe skew it. The recommended approach is to use the `Free Transform` tool in Photoshop and just move the corners until it fits the map.
@@ -190,4 +204,4 @@ You should see the square with a hole in the center, where your map is located.
 
 </details>
 
-Go to the next section of the tutorial: [Prepare the i3d files](README_i3d.md).
+Go to the next section of the tutorial: [Prepare the i3d files](create_background_terrain.md).

tutorials/README_giants_editor.md → docs/import_to_giants_editor.md

@@ -2,23 +2,24 @@
 
 So, at this point, you should have the `*.i3d` files with the background terrain. Now, let's import them into the Giants Editor.
 
-ℹ️ In this tutorials it's assumed that you have already generated the map, downloaded satellite images using this tutorial: [Download high-resolution satellite images](README_satellite_images.md), and created a background terrain as described in the previous tutorial: [Prepare the i3d files](README_i3d.md).
+ℹ️ In this tutorials it's assumed that you have already generated the map, downloaded satellite images using this tutorial: [Download high-resolution satellite images](download_satellite_images.md), and created a background terrain as described in the previous tutorial: [Prepare the i3d files](create_background_terrain.md).
 
 Here's what you need to do:
 
 1. Download and install the Giants Editor from the official website: [https://gdn.giants-software.com/downloads.php](https://gdn.giants-software.com/downloads.php). Note that for working with a map for Farming Simulator 25, you need to use the Giants Editor 10.0.0 or later, while for Farming Simulator 22, you need to use the Giants Editor 9.0.0 or later. If you try to open the map for the editor of the wrong version, it will crash.
 
 2. Open the main map file, for example for the Farming Simulator 25 it's a `map/map.i3d` file.
 
-3. Click on the `File` menu and select `Import...` select the `*.i3d` file with the background terrain. Note, that aftet the import, the terrain will have no textures, so don't worry, it's ok.
+3. Click on the `File` menu and select `Import...` select the `*.i3d` file with the background terrain.
 
 ![Import](https://github.com/user-attachments/assets/32145805-6583-4147-ac04-4c69d041b554)
 
 4. Postition the terrain in the correct place. You can use the `Transform` panel to move, rotate, and scale the terrain.
 
 ![Position](https://github.com/user-attachments/assets/8202b2f5-2286-4213-8785-c3779e9ad88a)
 
-5. Open the `Material Editing` panel (if it's not visible click on the `Window` menu and select `Material Editing`) and ensure that you've selected the correct object in the `Scenegraph` panel. Find the `Albedo map` and click on the `...` button to select the texture for the terrain. 
+5. If after the import you can't see the texture on the terrain, you need to add the texture manually.
+Open the `Material Editing` panel (if it's not visible click on the `Window` menu and select `Material Editing`) and ensure that you've selected the correct object in the `Scenegraph` panel. Find the `Albedo map` and click on the `...` button to select the texture for the terrain. 
 
 ![Albedo map](https://github.com/user-attachments/assets/20a197cd-dadf-4e61-8ad2-c6752d60fb17)
 
@@ -37,6 +38,6 @@ Here's what you need to do:
 So, we'are done here.<br>
 ℹ️ Please note, that is almost no way to align all background terrain with map perfectly without editing them in the 3D editor, Blender for example. You can find a lot of tutorials on YouTube on how to do it, this won't be covered here. Or you can just leave it as is and find the best possible position for the terrain, and maybe hiding the edges with some objects. It's up to you.<br>
 
-If you want, you can go back to the previous step: [Prepare the i3d files](README_i3d.md).<br>
+If you want, you can go back to the previous step: [Prepare the i3d files](create_background_terrain.md).<br>
 
 Happy mapping! 🚜🌾

maps4fs/toolbox/__init__.py

@@ -0,0 +1 @@
+# pylint: disable=missing-module-docstring