intermediate update

Signed-off-by: jparisu <[email protected]>

docs/index.rst

@@ -21,9 +21,10 @@ sIArena Documentation
    :maxdepth: 2
    :hidden:
 
-   /rst/elements/elements
-   /rst/elements/measure
-   /rst/elements/generation
+   /rst/modules/elements
+   /rst/modules/measure
+   /rst/modules/generation
+   /rst/modules/plotting
 
 
 .. toctree::

docs/rst/getting_started/tldr.rst

@@ -35,17 +35,79 @@ Check the :ref:`installation guide <getting_started_installation>` for more deta
 How to generate a terrain
 =========================
 
-.. warning::
+In order to generate a pseudorandom :ref:`elements_terrain`,
+the abstract class ``TerrainGenerator`` is provided.
+The main function use the following parameters:
 
-    Coming soon.
-    TODO
+- ``n: int`` number of rows
+- ``m: int`` number of columns
+- ``min_height: int = 0`` minimum height of the terrain
+- ``max_height: int = 99`` maximum height of the terrain
+- ``min_step: int = 1`` minimum step between two heights
+- ``abruptness: float = 0.2`` 0: smooth, 1: abrupt
+- ``seed: int = None`` seed for the random number generator
+- ``origin: Coordinate = None`` origin of the terrain
+- ``destination: Coordinate = None`` destination of the terrain
+
+There are 2 main generators: ``FocusedTerrainGenerator`` and ``PernilTerrainGenerator``.
+
+Create your terrain as follows:
+
+.. code-block:: py
+
+    from sIArena.terrain.generator.Generator import TerrainGenerator
+    from sIArena.terrain.generator.FocusedGenerator import FocusedGenerator
+    from sIArena.terrain.generator.PernilGenerator import PernilGenerator
+
+    N = 20
+    M = 20
+    MIN_HEIGHT = 0
+    MAX_HEIGHT = 10
+    MIN_STEP = 1
+    ABR = 0.1
+    ORIGIN = None
+    DESTINATION = None
+    SEED = 60
+    GENERATOR = PernilGenerator()
+
+    terrain = TerrainGenerator.generate_random_terrain(
+        GENERATOR,
+        n=N,
+        m=M,
+        min_height=MIN_HEIGHT,
+        max_height=MAX_HEIGHT,
+        min_step=MIN_STEP,
+        abruptness=ABR,
+        seed=SEED,
+        origin=ORIGIN,
+        destination=DESTINATION)
 
 
 =====================================
 How to write a path finding algorithm
 =====================================
 
-.. warning::
+Easy, create an algorithm that is able to retrieve a list of sequently :ref:`elements_coordinates`
+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]
 
-    Coming soon.
-    TODO
+    # measure your algorithm cost and time
+    min_cost, second, path = measure_function(my_algorithm, terrain)

docs/rst/elements/elements.rst → docs/rst/modules/elements.rst

@@ -11,13 +11,10 @@ a :ref:`elements_terrain` and a :ref:`elements_path`.
 
 
 
-..include:: rst/elements/coordinate.rst
+.. include:: rst/modules/elements/coordinate.rst
 
-..include:: rst/elements/terrain.rst
+.. include:: rst/modules/elements/terrain.rst
 
-..include:: rst/elements/path.rst
+.. include:: rst/modules/elements/path.rst
 
-
-=======
-Example
-=======
+.. include:: rst/modules/elements/example.rst

docs/rst/modules/elements/example.rst

@@ -0,0 +1,68 @@
+
+.. _example:
+
+=======
+Example
+=======
+
+The following snippet shows the different features of the elements:
+
+.. code-block:: python
+
+    from sIArena.terrain.Terrain import Coordinate, Path, Terrain
+
+    # TERRAIN
+    ##########
+
+    # Create a matrix with heights of the terrain
+    matrix = [[6, 5, 4, 1],
+              [5, 4, 2, 0],
+              [4, 1, 0, 0]]
+
+    # Create a terrain with the matrix with different destination that default
+    terrain = Terrain(matrix, destination=(2, 2))
+
+    # Get size
+    terrain.n  # Output: 3
+    terrain.m  # Output: 4
+
+    # Get origin and destination
+    terrain.origin  # Output: (0, 0)
+    terrain.destination  # Output: (2, 2)
+
+    # Get the height of the terrain in a coordinate
+    terrain[(0, 0)]  # Output: 6
+    terrain[(2, 1)]  # Output: 1
+
+    str(terrain)  # Output:
+    # +---+---+---+---+
+    # |*6 | 5 | 4 | 1 |
+    # +---+---+---+---+
+    # | 5 | 4 | 2 | 0 |
+    # +---+---+---+---+
+    # | 4 | 1 |x0 | 0 |
+    # +---+---+---+---+
+
+    # BUILDING PATH
+    ################
+
+    # Get the cost of a step from a coordinate to another
+    terrain.get_cost((0, 0), (0, 1))  # Output: 1
+    terrain.get_cost((0, 1), (0, 0))  # Output: 2
+
+    # Get the neighbors of a coordinate
+    terrain.get_neighbors((0, 0))  # Output: [(0, 1), (1, 0)]
+    terrain.get_neighbors((1, 1))  # Output: [(0, 1), (1, 0), (1, 2), (2, 1)]
+
+
+    # PATH
+    #######
+
+    # Create a path with the terrain that goes from origin to destination
+    path = [(0,0), (0,1), (0,2), (0,3), (1,3), (1,2), (2,2)]
+
+    # Check the path is complete
+    terrain.is_valid_path(path, terrain)  # Output: True
+
+    # Check the path cost
+    terrain.get_path_cost(path, terrain)  # Output: 12

docs/rst/elements/terrain.rst → docs/rst/modules/elements/terrain.rst

@@ -37,21 +37,36 @@ Built-in Methods
 - ``str``: returns a string representation of the matrix of the terrain.
   The origin and destination cells are marked with the characters ``+`` and ``x`` respectively.
 
-- ``len``: returns the number of cells in the terrain.
-  Returns a tuple with ``(n,m)``.
-
-- ``getitem []``: returns the value of the cell at the given coordinates.
+- ``getitem [Coordinate]``: returns the value of the cell at the given coordinates.
+  *i.e.* ``terrain[(0,0)]``.
 
 - ``ctor``: constructor that receives a matrix.
   - ``matrix``: numpy matrix of size ``NxM``
-  - ``origin``: ``tuple(int,int)`` with the coordinates of the origin cell
+  - ``origin``: ``Coordinate`` with the coordinates of the origin cell
     If ``None`` is provided, the origin will be set to ``(0,0)``
-  - ``destination``: ``tuple(int,int)`` with the coordinates of the destination cell
+  - ``destination``: ``Coordinate`` with the coordinates of the destination cell
     If ``None`` is provided, the destination will be set to ``(n-1,m-1)``
   - ``cost_function``: function that receives 2 integers ``x,y`` and returns the cost of moving from one cell with value ``x`` to another with value ``y``
     In case is not provided, the :ref:`elements_terrain_default_cost_function` will be used.
 
 
+Methods
+-------
+
+- ``size``: returns a tuple with ``(n,m)``.
+- ``get_neighbors``: returns a list of the coordinates of the cells that are adjacent to the given cell.
+  - ``pos``: ``Coordinate``
+- ``get_cost``: returns the cost of moving from one cell to another.
+  - ``pos1``: ``Coordinate``
+  - ``pos2``: ``Coordinate``
+- ``get_path_cost``: returns the cost of a whole Path.
+  - ``path``: ``Path``
+- ``is_complete_path``: returns ``True`` if the given Path is valid and complete.
+  - ``path``: ``Path``
+
+*Some of this methods use the element* :ref:`elements_path` *that is seeing afterwards.*
+
+
 .. _elements_terrain_cost_function:
 
 Cost Function

docs/rst/elements/generation.rst → docs/rst/modules/generation.rst

@@ -1,4 +1,4 @@
-.. _elements_generation:
+.. _generation:
 
 ################
 Generate Terrain

docs/rst/modules/measure.rst

@@ -0,0 +1,10 @@
+.. _measure:
+
+#############
+Measure tools
+#############
+
+.. warning::
+
+    Coming soon.
+    TODO