Fill the documentation (#8)

* Fill the documentation Signed-off-by: jparisu <[email protected]> * intermediate update Signed-off-by: jparisu <[email protected]> * fix some minor stuff Signed-off-by: jparisu <[email protected]> * intermediate update Signed-off-by: jparisu <[email protected]> * Add tutorial Signed-off-by: jparisu <[email protected]> * fox minor changes Signed-off-by: jparisu <[email protected]> * final details Signed-off-by: jparisu <[email protected]> --------- Signed-off-by: jparisu <[email protected]>
jparisu · Feb 4, 2024 · e157dc4 · e157dc4
1 parent a1acf22
commit e157dc4
Show file tree

Hide file tree

Showing 36 changed files with 823 additions and 109 deletions.
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -0,0 +1,4 @@
+{
+    "restructuredtext.syntaxHighlighting.disabled": true,
+    "esbonio.sphinx.confDir": ""
+}
diff --git a/README.md b/README.md
@@ -2,9 +2,9 @@
 
 [![Documentation Status](https://readthedocs.org/projects/siarena/badge/?version=latest)](https://siarena.readthedocs.io/en/latest/?badge=latest)
 
-Educational motive repository form searching algorithms.
+Educational **Framework** for testing **AI** path finding algorithms over maps and terrains.
 
-**Framework** for testing **AI** searching algorithms over maps and terrains.
+![sIArena](docs/resources/images/3dplot_big_solved.png)
 
 
 ## Documentation

diff --git a/docs/index.rst b/docs/index.rst
@@ -17,13 +17,14 @@ sIArena Documentation
 
 
 .. toctree::
-   :caption: Elements
+   :caption: Modules
    :maxdepth: 2
    :hidden:
 
-   /rst/elements/terrain
-   /rst/elements/measure
-   /rst/elements/generation
+   /rst/modules/elements
+   /rst/modules/measure
+   /rst/modules/generation
+   /rst/modules/plotting
 
 
 .. toctree::

diff --git a/docs/resources/images/2dplot_10_10.png b/docs/resources/images/2dplot_10_10.png
diff --git a/docs/resources/images/2dplot_10_10_solved.png b/docs/resources/images/2dplot_10_10_solved.png
diff --git a/docs/resources/images/2dplot_3_4_path.png b/docs/resources/images/2dplot_3_4_path.png
diff --git a/docs/resources/images/2dplot_5_5.png b/docs/resources/images/2dplot_5_5.png
diff --git a/docs/resources/images/2dplot_big.png b/docs/resources/images/2dplot_big.png
diff --git a/docs/resources/images/2dplot_big_solved_down.png b/docs/resources/images/2dplot_big_solved_down.png
diff --git a/docs/resources/images/3dplot_10_10.png b/docs/resources/images/3dplot_10_10.png
diff --git a/docs/resources/images/3dplot_10_10_solved.png b/docs/resources/images/3dplot_10_10_solved.png
diff --git a/docs/resources/images/3dplot_3_4_path.png b/docs/resources/images/3dplot_3_4_path.png
diff --git a/docs/resources/images/3dplot_5_5.png b/docs/resources/images/3dplot_5_5.png
diff --git a/docs/resources/images/3dplot_big.png b/docs/resources/images/3dplot_big.png
diff --git a/docs/resources/images/3dplot_big_solved.png b/docs/resources/images/3dplot_big_solved.png
diff --git a/docs/resources/images/3dplot_big_solved_down.png b/docs/resources/images/3dplot_big_solved_down.png
diff --git a/docs/resources/scripts/tutorial.py b/docs/resources/scripts/tutorial.py
@@ -0,0 +1,101 @@
+
+#####################################################################
+
+from sIArena.terrain.Terrain import Coordinate, Terrain, Path
+from sIArena.terrain.generator.PernilGenerator import PernilGenerator
+
+terrain = PernilGenerator().generate_random_terrain(
+    n=25,
+    m=25,
+    min_height=0,
+    max_height=100,
+    min_step=25,
+    abruptness=0.1,
+    seed=60,
+    origin=None,
+    destination=None)
+
+# To print the terrain in ascii format
+print(terrain)
+
+
+#####################################################################
+
+from sIArena.terrain.plot.plot_2D import plot_terrain_2D
+from sIArena.terrain.plot.plot_3D import plot_terrain_3D
+
+plot_terrain_2D(terrain)
+plot_terrain_3D(terrain, angles=[(80, 10), (30, 190), (30, 10)])
+
+
+#####################################################################
+
+# Get the terrain size
+n, m = terrain.size()
+
+# Get origin and destination coordinates
+origin = terrain.origin
+destination = terrain.destination
+
+# Check the possible neighbors of the origin (thus, the possible next step of the path)
+neigs = terrain.get_neighbors(origin)
+
+# Check the cost from the origin to each neighbor
+costs = [terrain.get_cost(origin, neig) for neig in neigs]
+
+
+#####################################################################
+
+from sIArena.terrain.Terrain import Coordinate, Terrain, Path
+
+def find_path(terrain: Terrain) -> Path:
+
+    # Create a path that starts in origin
+    path = [origin]
+
+    # Go to the buttom of the map (assuming destination is in [N-1,M-1])
+    for i in range(n-1):
+        path.append((path[-1][0] + 1, path[-1][1]))
+
+    # Go to the right of the map (assuming destination is in [N-1,M-1])
+    for i in range(m-1):
+        path.append((path[-1][0], path[-1][1] + 1))
+
+    # Return the path
+    return path
+
+
+#####################################################################
+
+# Get the path solution
+path = find_path(terrain)
+
+# Check if a path is complete (it must be with our implementation)
+is_complete = terrain.is_complete_path(path)
+
+# Calculate the cost of a path
+cost = terrain.get_path_cost(path)
+
+print(f"The path {path} with cost {cost} {'is' if is_complete else 'is not'} complete.")
+
+
+#####################################################################
+
+from sIArena.terrain.plot.plot_2D import plot_terrain_2D
+from sIArena.terrain.plot.plot_3D import plot_terrain_3D
+
+plot_terrain_2D(terrain, paths=[path])
+plot_terrain_3D(terrain, paths=[path], angles=[(80, 10), (30, 190), (30, 10)])
+
+
+#####################################################################
+
+from sIArena.measurements.measurements import measure_function
+
+min_cost, second, min_path = measure_function(
+    find_path,
+    terrain,
+    iterations=5,
+    debug=True)
+
+print(f"Minimum cost: {min_cost} found in {second} seconds:\n{path}")
diff --git a/docs/rst/elements/generation.rst b/docs/rst/elements/generation.rst
diff --git a/docs/rst/elements/measure.rst b/docs/rst/elements/measure.rst
diff --git a/docs/rst/elements/terrain.rst b/docs/rst/elements/terrain.rst
diff --git a/docs/rst/getting_started/installation.rst b/docs/rst/getting_started/installation.rst
@@ -1,4 +1,4 @@
-.. _getting_started_installation:
+.. _installation:
 
 ############
 Installation

diff --git a/docs/rst/getting_started/tldr.rst b/docs/rst/getting_started/tldr.rst
@@ -1,21 +1,24 @@
-.. _getting_started_tldr:
+.. _tldr:
 
 #####
 TL;DR
 #####
 
+Too hard to read? Here is a quick summary of the project.
+
+.. contents::
+    :local:
+    :backlinks: none
+    :depth: 2
+
 ================
 Project Overview
 ================
 
 This project helps you to generate 2D terrains, that are matrix of integers, with a point of origin and a point of destination.
-Over these terrains you have several features:
+The main goal is to develop an algorithm that is able to find the best path from the origin to the destination.
 
-- You can print it in the console
-- You can plot it in a ``matplotlib`` 2D plot
-- You can plot it in 3D with different angles
-- **You can check the total length of a given path from origin to destination**
-- You can even draw the paths in the plots previously mentioned
+Check :ref:`elements` for more details.
 
 
 ============
@@ -28,24 +31,62 @@ Just use the following command in your notebook:
 
     !pip install git+https://github.com/jparisu/sIArena.git
 
-Check the :ref:`installation guide <getting_started_installation>` for more details.
+Check the :ref:`installation guide <installation>` for more details.
 
 
 =========================
 How to generate a terrain
 =========================
 
-.. warning::
+Use the following code changing some parameters:
+
+.. code-block:: py
+
+    from sIArena.terrain.generator.Generator import TerrainGenerator
+    from sIArena.terrain.generator.FocusedGenerator import FocusedGenerator
+    from sIArena.terrain.generator.PernilGenerator import PernilGenerator
+
+    terrain = PernilGenerator().generate_random_terrain(
+        n=20,
+        m=20,
+        min_height=0,
+        max_height=10,
+        min_step=1,
+        abruptness=0.1,
+        seed=0,
+        origin=(0,0),
+        destination=(19,19))
 
-    Coming soon.
-    TODO
+Check :ref:`generation` for more details.
 
 
 =====================================
 How to write a path finding algorithm
 =====================================
 
-.. warning::
+Easy, create an algorithm that is able to retrieve a list of sequently :ref:`elements_coordinate`
+that goes from the origin to the destination of the terrain.
+
+
+.. code-block:: py
+
+    from sIArena.terrain.Terrain import Coordinate, Path, Terrain
+    from sIArena.measurements.measurements import measure_function
+
+    terrain = ...  # Terrain already created
+
+    def my_algorithm(terrain: Terrain) -> Path:
+        path = [terrain.origin]
+
+        # To check the possible next cells:
+        terrain.get_neighbors(path[-1])
+        # Add new sequently coordinates till the destination
+        path.add(...)
+        # ...
+
+        return path + [terrain.destination]
+
+    # measure your algorithm cost and time
+    min_cost, second, path = measure_function(my_algorithm, terrain)
 
-    Coming soon.
-    TODO
+Check :ref:`measure` for more details.