Merge remote-tracking branch 'iwatkot/main'

# Conflicts:
#	maps4fs/__init__.py

README.md

@@ -115,7 +115,7 @@ Check out the [Docker FAQ](docs/FAQ_docker.md) if you have any questions.<br>
 ```bash
 pip install maps4fs
 ```
-And refer to the [Python package](#option-3-python-package) section to learn how to use it.<br>
+And refer to the [Python package or run from the source](#option-3-python-package-or-source-code) section to learn how to use it.<br>
 
 ## Overview
 The core idea is coming from the awesome [maps4cim](https://github.com/klamann/maps4cim) project.<br>
@@ -175,7 +175,7 @@ docker run -d -p 8501:8501 --name maps4fs iwatkot/maps4fs
 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
+### Option 3: Python package or source code
 🔴 Recommended for developers.  
 🗺️ Supported map sizes: 2x2, 4x4, 8x8, 16x16 km and any custom size.  
 ⚙️ Advanced settings: enabled.   
@@ -186,11 +186,50 @@ You can use the Python package to generate maps. Follow these steps:
 ```bash
 pip install maps4fs
 ```
+
+Or clone the repository and install the package from the source code:
+```bash
+git clone https://github.com/iwatkot/maps4fs.git
+cd maps4fs
+dev/create_venv.ps1 # for Windows
+sh dev/create_venv.sh # for Linux
+
+# Activate the virtual environment.
+./venv/scripts/activate # for Windows
+source venv/bin/activate # for Linux
+
+# Edit the demo.py file to set the parameters.
+python demo.py
+```
+
+
 2. Import the Game class and create an instance of it:
 ```python
 import maps4fs as mfs
 
-game = mfs.Game.from_code("FS25")
+game_code = "fs25"
+game = mfs.Game.from_code(game_code)
+
+dtm_provider = mfs.SRTM30Provider
+dtm_provider_settings = mfs.SRTM30ProviderSettings(easy_mode=True, power_factor=0)
+
+lat, lon = 45.28, 20.23
+coordinates = (lat, lon)
+size = 2048
+rotation = 25
+
+map_directory = "map_directory"
+os.makedirs(map_directory, exist_ok=True)
+
+mp = mfs.Map(
+    game,
+    dtm_provider,
+    dtm_provider_settings,
+    coordinates,
+    size,
+    rotation,
+    map_directory,
+)
 ```
 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.<br>
 Structure example:<br>
@@ -203,28 +242,17 @@ Structure example:<br>
 
 So it's recommended to download the `data` directory from the repository and place it in the root of your project.<br>
 
-3. Create an instance of the Map class:
-```python
-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:
+3. Launch the generation process.  
 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.
 ```python
-for active_component in map.generate():
-    print(active_component)
+for component_name in mp.generate():
+    print(f"Generating {component_name}...")
 ```
 
 The map will be saved in the `map_directory` directory.
 
+➡️ Check out the [demo.py](demo.py) file for a complete example.
+
 ## 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>
 

demo.py

@@ -0,0 +1,102 @@
+# This is a demo script that shows how to use the maps4fs library.
+# Option 1: To use from the source code:
+# ➡️ git clone https://github.com/iwatkot/maps4fs.git
+# ➡️ cd maps4fs
+# For Windows
+# ➡️ dev/create_venv.ps1
+# ➡️ ./venv/scripts/activate
+# For Linux
+# ➡️ sh dev/create_venv.sh
+# ➡️ source venv/bin/activate
+# Option 2: To install as PyPI package:
+# Create a new virtual environment.
+# ➡️ pip install maps4fs
+# Edit the demo.py file
+# And run the script
+# ➡️ python demo.py
+
+import os
+
+import maps4fs as mfs
+
+# 1️⃣ Define the game (FS22 or FS25).
+game_code = "fs25"
+game = mfs.Game.from_code(game_code)
+
+# 2️⃣ Choose the DTM Provider and define it's settings.
+dtm_provider = mfs.SRTM30Provider
+dtm_provider_settings = mfs.SRTM30ProviderSettings(easy_mode=True, power_factor=0)
+
+# 3️⃣ Define the coordinates of the central point of the map, size and rotation.
+lat, lon = 45.28, 20.23
+coordinates = (lat, lon)
+size = 2048
+rotation = 25
+
+# 4️⃣ Define the output directory.
+map_directory = "map_directory"
+os.makedirs(map_directory, exist_ok=True)
+
+# 5️⃣ Optional: use a custom OSM file.
+osm_file = "path/to/osm_file.osm"
+
+# 6️⃣ Optional: advanced settings. You can use the default settings, but
+# it's recommended to change them according to your needs.
+dem_settings = mfs.DEMSettings(multiplier=1, blur_radius=15, plateau=3000, water_depth=2000)
+background_settings = mfs.BackgroundSettings(
+    generate_background=True,
+    generate_water=True,
+    resize_factor=2,
+    remove_center=True,
+    apply_decimation=True,
+    decimation_percent=50,
+    decimation_agression=4,
+)
+grle_settings = mfs.GRLESettings(farmland_margin=10, random_plants=True, add_farmyards=True)
+i3d_settings = mfs.I3DSettings(forest_density=8)
+texture_settings = mfs.TextureSettings(
+    dissolve=True,
+    fields_padding=10,
+    skip_drains=True,
+)
+spline_settings = mfs.SplineSettings(spline_density=0)
+satellite_settings = mfs.SatelliteSettings(download_images=True, zoom_level=18)
+
+# 7️⃣ Optional: define custom tree and textures schemas.
+# Default schemas can be found in the `data` directory of the repository.
+texture_custom_schema = [
+    # Your texture schema here.
+]
+tree_custom_schema = [
+    # Your tree schema here.
+]
+
+# 8️⃣ Create an instance of the Map class with specified settings.
+mp = mfs.Map(
+    game,
+    dtm_provider,
+    dtm_provider_settings,
+    coordinates,
+    size,
+    rotation,
+    map_directory,
+    # custom_osm=osm_file,
+    dem_settings=dem_settings,
+    background_settings=background_settings,
+    grle_settings=grle_settings,
+    i3d_settings=i3d_settings,
+    texture_settings=texture_settings,
+    spline_settings=spline_settings,
+    satellite_settings=satellite_settings,
+    # texture_custom_schema=texture_custom_schema,
+    # tree_custom_schema=tree_custom_schema,
+)
+
+# 9️⃣ Launch the generation process.
+for component_name in mp.generate():
+    print(f"Generating {component_name}...")
+
+# 1️⃣0️⃣ Optional: save the previews of the generated components.
+previews_paths = mp.previews()
+for preview_path in previews_paths:
+    print(f"Preview saved to {preview_path}")

maps4fs/__init__.py

@@ -1,7 +1,7 @@
 # pylint: disable=missing-module-docstring
 from maps4fs.generator.dtm.dtm import DTMProvider
-from maps4fs.generator.dtm.srtm import SRTM30Provider
-from maps4fs.generator.dtm.usgs import USGSProvider
+from maps4fs.generator.dtm.srtm import SRTM30Provider, SRTM30ProviderSettings
+from maps4fs.generator.dtm.usgs import USGSProvider, USGSProviderSettings
 from maps4fs.generator.dtm.bavaria import Bavaria1mProvider
 from maps4fs.generator.game import Game
 from maps4fs.generator.map import Map
@@ -10,6 +10,7 @@
     DEMSettings,
     GRLESettings,
     I3DSettings,
+    SatelliteSettings,
     SettingsModel,
     SplineSettings,
     TextureSettings,