diff --git a/docs/resources/images/3dplot_big_solved.png b/docs/resources/images/3dplot_big_solved.png index ac30f1e..981c030 100644 Binary files a/docs/resources/images/3dplot_big_solved.png and b/docs/resources/images/3dplot_big_solved.png differ diff --git a/docs/rst/getting_started/tldr.rst b/docs/rst/getting_started/tldr.rst index c9774ac..a3c24f3 100644 --- a/docs/rst/getting_started/tldr.rst +++ b/docs/rst/getting_started/tldr.rst @@ -4,18 +4,21 @@ 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. ============ @@ -35,23 +38,7 @@ Check the :ref:`installation guide ` for more deta How to generate a terrain ========================= -In order to generate a pseudorandom :ref:`elements_terrain`, -the abstract class ``TerrainGenerator`` is provided. -The main function use the following parameters: - -- ``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: +Use the following code changing some parameters: .. code-block:: py @@ -59,35 +46,25 @@ Create your terrain as follows: 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) + 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)) + +Check :ref:`generation` for more details. ===================================== How to write a path finding algorithm ===================================== -Easy, create an algorithm that is able to retrieve a list of sequently :ref:`elements_coordinates` +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. @@ -111,3 +88,5 @@ that goes from the origin to the destination of the terrain. # measure your algorithm cost and time min_cost, second, path = measure_function(my_algorithm, terrain) + +Check :ref:`measure` for more details. diff --git a/docs/rst/modules/elements.rst b/docs/rst/modules/elements.rst index 994c23e..c6e212d 100644 --- a/docs/rst/modules/elements.rst +++ b/docs/rst/modules/elements.rst @@ -4,17 +4,20 @@ Elements ######## +.. contents:: + :local: + :backlinks: none + :depth: 2 + In the following sections, we will describe the different elements in this project. The main elements are a :ref:`elements_coordinate`, a :ref:`elements_terrain` and a :ref:`elements_path`. +.. toctree:: + :maxdepth: 2 - -.. include:: rst/modules/elements/coordinate.rst - -.. include:: rst/modules/elements/terrain.rst - -.. include:: rst/modules/elements/path.rst - -.. include:: rst/modules/elements/example.rst + elements/coordinate.rst + elements/terrain.rst + elements/path.rst + elements/example.rst diff --git a/docs/rst/modules/elements/path.rst b/docs/rst/modules/elements/path.rst index 20327bd..d164222 100644 --- a/docs/rst/modules/elements/path.rst +++ b/docs/rst/modules/elements/path.rst @@ -9,7 +9,7 @@ Path from sIArena.terrain.Terrain import Path -A :term:`Path` is a sequence of :ref:`elements_coordinates` that represents a route from one point to another in a :ref:`elements_terrain`. +A :term:`Path` is a sequence of :ref:`elements_coordinate` that represents a route from one point to another in a :ref:`elements_terrain`. In order to be **valid**, each step of the path (each pair of consecutive coordinates) must be a movement of one step in one of the four cardinal directions (up, down, left, right). diff --git a/docs/rst/modules/elements/terrain.rst b/docs/rst/modules/elements/terrain.rst index 3f1dde8..f771baa 100644 --- a/docs/rst/modules/elements/terrain.rst +++ b/docs/rst/modules/elements/terrain.rst @@ -26,7 +26,7 @@ Attributes - ``n``: number of rows - ``m``: number of columns -- ``matrix``: numpy matrix of size ``NxM`` +- ``matrix``: ``numpy`` matrix of size ``NxM`` - ``origin``: ``tuple(int,int)`` with the coordinates of the origin cell - ``destination``: ``tuple(int,int)`` with the coordinates of the destination cell - ``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`` @@ -41,12 +41,16 @@ Built-in Methods *i.e.* ``terrain[(0,0)]``. - ``ctor``: constructor that receives a matrix. - - ``matrix``: numpy matrix of size ``NxM`` - - ``origin``: ``Coordinate`` with the coordinates of the origin cell + + - ``matrix``: ``numpy`` matrix of size ``NxM`` + + - ``origin``: ``Coordinate`` with the coordinates of the origin cell. If ``None`` is provided, the origin will be set to ``(0,0)`` - - ``destination``: ``Coordinate`` 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`` + + - ``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. @@ -133,7 +137,7 @@ The origin and destination cells are marked with the characters ``+`` and ``x`` 2D plot ******* -.. image:: resources/image/2dplot_55.png +.. image:: /resources/image/2dplot_5_5.png In order to learn how to visualize a 2D plot of the terrain, please refer to the :ref:`plotting_2d` section. @@ -141,6 +145,6 @@ In order to learn how to visualize a 2D plot of the terrain, please refer to the 3D plot ******* -.. image:: resources/image/3dplot_55.png +.. image:: /resources/image/3dplot_5_5.png In order to learn how to visualize a 3D plot of the terrain, please refer to the :ref:`plotting_3d` section. diff --git a/docs/rst/modules/generation.rst b/docs/rst/modules/generation.rst index 7f514ae..2642b41 100644 --- a/docs/rst/modules/generation.rst +++ b/docs/rst/modules/generation.rst @@ -8,3 +8,18 @@ Generate Terrain Coming soon. TODO + +.. contents:: + :local: + :backlinks: none + :depth: 2 + +- ``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 diff --git a/docs/rst/modules/measure.rst b/docs/rst/modules/measure.rst index 192d142..013e55b 100644 --- a/docs/rst/modules/measure.rst +++ b/docs/rst/modules/measure.rst @@ -8,3 +8,8 @@ Measure tools Coming soon. TODO + +.. contents:: + :local: + :backlinks: none + :depth: 2 diff --git a/docs/rst/modules/plotting.rst b/docs/rst/modules/plotting.rst index 684ee5a..2b6bc90 100644 --- a/docs/rst/modules/plotting.rst +++ b/docs/rst/modules/plotting.rst @@ -5,6 +5,11 @@ Plot Terrain ############ +.. contents:: + :local: + :backlinks: none + :depth: 2 + Certain functions allow to plot a :ref:`elements_terrain` to visualize the heights easily. @@ -29,7 +34,7 @@ Parameters - ``paths_legends: List[str] = None``: The legend message for each path - ``add_cost_to_legend: bool = False``: If True, the cost of the path will be added as legend - ``colors: List[str] = ['r', 'y', 'm', 'k', 'c', 'g', 'b']``: The colors to use for each paths -- ``cmap: str = 'terrain'``: The colormap to use for the terrain +- ``cmap: str = 'terrain'``: The ``colormap`` to use for the terrain - ``title: str = 'Terrain'``: The title of the plot Example @@ -52,7 +57,7 @@ Example paths_legends=['Path 1'], add_cost_to_legend=True) -.. image:: resources/images/2dplot_3_4_path.png +.. image:: /resources/images/2dplot_3_4_path.png .. _plotting_3d: @@ -76,7 +81,7 @@ Parameters - ``angles: List[tuple] = [(45, 45), (45, 225)]``: The angles from where to plot the terrain - ``paths: List[Path] = []``: The paths to plot - ``colors: List[str] = ['r', 'y', 'm', 'k', 'c', 'g', 'b']``: The colors to use for each paths -- ``cmap: str = 'terrain'``: The colormap to use for the terrain +- ``cmap: str = 'terrain'``: The ``colormap`` to use for the terrain - ``title: str = 'Terrain'``: The title of the plot Example @@ -98,7 +103,7 @@ Example angles=[(80, 10), (30, 190), (30, 10)], paths=[path]) -.. image:: resources/images/3dplot_3_4_path.png +.. image:: /resources/images/3dplot_3_4_path.png @@ -107,9 +112,9 @@ Examples When used in bigger terrains, the result is much more interesting. -.. image:: resources/images/2dplot_10_10_solved.png +.. image:: /resources/images/2dplot_10_10_solved.png -.. image:: resources/images/3dplot_10_10_solved.png +.. image:: /resources/images/3dplot_10_10_solved.png .. warning::