added navigation in programming

programming/index.rst

@@ -59,4 +59,5 @@ manual by studying the :ref:`Reference Section <reference>`.
    threading
    subclassing
    pandai/index
+   navigation/index
    using-cpp/index

programming/navigation/bam-serialization.rst

@@ -0,0 +1,66 @@
+.. _bam-serialization:
+
+BAM serialization
+=================
+
+Panda3D provides the feature to write the Panda3D objects to the disk 
+using the BAM operations. In the navigation library, the BAM operations have 
+been implemented over the NavMeshNode class.
+
+.. only:: python
+
+   .. code-block:: python
+
+      navmeshnode = navigation.NavMeshNode("firstnavmeshnode", navmesh)
+      navmeshnodepath = scene.attach_new_node(navmeshnode)
+
+.. only:: cpp
+
+   .. code-block:: cpp
+
+      NavMeshNode navmeshnode = new NavMeshNode("firstnavmeshnode", navmesh);
+      NodePath navmeshnodepath = scene.attach_new_node(navmeshnode);
+
+
+Write BAM
+~~~~~~~~~
+
+You can write the 'navmeshnodepath' to the disk as a BAM file.
+
+.. only:: python
+
+   .. code-block:: python
+
+      navmeshnodepath.write_bam_file("firstnavmeshnode.bam")
+
+.. only:: cpp
+
+   .. code-block:: cpp
+
+      navmeshnodepath.write_bam_file("firstnavmeshnode.bam");
+
+The BAM File 'firstnavmeshnode.bam' is stored on the disk and can be used directly 
+in the games or the programs without building and navigation mesh again. This 
+helps in saving time and computation power.
+
+Read BAM
+~~~~~~~~
+
+You can read the BAM File from the disk and load it as NodePath to NavMeshNode.
+
+.. only:: python
+
+   .. code-block:: python
+
+      navmesh = loader.load_model("firstnavmeshnode.bam")
+
+.. only:: cpp
+
+   .. code-block:: cpp
+
+      PandaFramework framework;
+      framework.open_framework(argc, argv);
+      framework.set_window_title("My Panda3D Window");
+      WindowFramework *window = framework.open_window();
+      NodePath navmesh = window->load_model(framework.get_models(), "firstnavmeshnode.bam");
+

programming/navigation/build-mesh.rst

@@ -0,0 +1,111 @@
+.. _build-mesh:
+
+Building Navigation Mesh
+========================
+
+Implementation:
+
+Following are the steps to build a basic navigation mesh. 
+
+Step 1:
+
+.. only:: python
+
+   To use the navmeshgen library into your game you need to import it into your game code.
+   The generated mesh is stored as an object of class NavMesh, which can be accessed by importing navigation.
+
+   .. code-block:: python
+
+      from panda3d import navmeshgen
+      from panda3d import navigation
+
+.. only:: cpp
+
+   The headers required to be included for building mesh are navMeshBuilder and navMesh.
+
+   .. code-block:: cpp
+
+      #include "pandaFramework.h"
+      #include "pandaSystem.h"
+      #include "navMesh.h"
+      #include "navMeshBuilder.h"
+
+Step 2:
+
+Create a geom primitive or load an external model. Here we load the model called 'street.obj'
+
+.. only:: python
+
+   .. code-block:: python
+
+      scene = loader.load_model("samples/street-navigation/models/street.obj")
+
+.. only:: cpp
+
+   .. code-block:: cpp
+
+      PandaFramework framework;
+      framework.open_framework(argc, argv);
+      framework.set_window_title("My Panda3D Window");
+      WindowFramework *window = framework.open_window();
+      NodePath scene = window->load_model(framework.get_models(), "models/environment");
+
+Now the model is loaded in the NodePath 'scene'
+
+Step 3:
+
+Create an object for the class NavMeshBuilder via:
+
+.. only:: python
+
+   .. code-block:: python
+
+     builder = navmeshgen.NavMeshBuilder()
+
+.. only:: cpp
+
+   .. code-block:: cpp
+
+     NavMeshBuilder builder = new NavMeshBuilder()
+
+Step 4:
+
+Now, we shall build the navigation mesh for our model stored in NodePath 'scene'.
+
+.. only:: python
+
+   .. code-block:: python
+
+      builder.from_node_path(scene)
+
+.. only:: cpp
+
+   .. code-block:: cpp
+
+      builder.from_node_path(scene)
+
+Step 5:
+
+Finally, we build the navigation mesh using the build function. 
+The output mesh is stored as an object of class NavMesh.
+
+.. only:: python
+
+   .. code-block:: python
+
+      navmesh = builder.build()
+
+.. only:: cpp
+
+   .. code-block:: cpp
+
+      PT(NavMesh) navmesh = builder.build()
+
+Here, 'navmesh' is the object of class NavMesh and has the generated mesh.
+
+This is how easy it is to get a basic navigation mesh generated!
+
+Next Step:
+
+Now that you have a basic working program, you should proceed to the
+parameters page and see how navigation mesh varies with parameters.

programming/navigation/getting-started.rst

@@ -0,0 +1,14 @@
+.. _getting-started:
+
+Getting Started
+===============
+
+Navigation and Navmeshgen are two libraries which can be used together to perform fast pathfinding operations on Panda3d geoms.
+
+To use the navmeshgen library into your game you need to import it into your game
+code.
+The generated mesh is stored as an object of class NavMesh, which can be accessed by importing navigation.
+
+The navmeshgen library has the class NavMeshBuilder, the main operation of which is to build the navigation mesh.
+The navigation library has the class NavMesh, which stores the mesh build by NavMeshBuilder or some other library.
+It has also has class NavMeshQuery, which is responsible for handling the query operations like pathfinding over the mesh. 

programming/navigation/index.rst

@@ -0,0 +1,21 @@
+.. _navigation:
+
+Pathfinding using Navigation
+============================
+
+Panda3D is integrated with the Recast-Detour library as navmeshgen and navigation libraries.
+
+Navmeshgen is an AI library for Panda3D which, for a given geom, generates a navigation mesh, a mesh containing only the walkable surfaces.
+
+Navigation is an AI library for Panda3D which operates on an input navigation mesh. The input navigation can be generated using navmeshgen library or by the user's preferred external library. The navigation library lets us query over the navigation mesh and find the path between any two points over the mesh.
+
+
+.. toctree::
+   :maxdepth: 2
+
+   getting-started
+   build-mesh
+   set-actor-parameters
+   visualize-mesh
+   path-query
+   bam-serialization

programming/navigation/path-query.rst

@@ -0,0 +1,154 @@
+.. _path-query:
+
+Pathfinding on NavMesh
+======================
+
+The most important feature of navigation library is pathfinding.
+The library uses A* pathfinding algorithm over polygons of navigation 
+mesh, though you do not need to worry about those stuffs.
+
+Update the Code
+~~~~~~~~~~~~~~~
+
+.. only:: cpp
+
+   Include the header required for making queries on navmesh:
+
+   .. code-block:: cpp
+
+      #include "navMeshQuery.h"
+
+Make a object of NavMeshQuery Class which will then do query operations 
+for pathfinding.
+
+.. only:: python
+
+   .. code-block:: python
+
+      query = navigation.NavMeshQuery(navmesh)
+
+.. only:: cpp
+
+   .. code-block:: cpp
+
+      NavMeshQuery query = new NavMeshQuery(navmesh);
+
+Now, you should define the two points between which path has to be found.
+
+.. only:: python
+
+   .. code-block:: python
+
+      from panda3d.core import LPoint3
+      pos1 = LPoint3(0, 0, 0);
+      pos2 = LPoint3(50, 60, 3);
+
+.. only:: cpp
+
+   .. code-block:: cpp
+
+      #include "lpoint3.h"
+      LPoint3 pos1 = new Lpoint3(0,0,0);
+      LPoint3 pos2 = new Lpoint3(50,60,3);
+
+
+To find the path between the two positions, you can simple use the following:
+
+.. only:: python
+
+   .. code-block:: python
+
+      path = query.find_path(pos1, pos2)
+
+.. only:: cpp
+
+   .. code-block:: cpp
+
+      PTA_LVecBase3 path = query.find_path(pos1, pos2);
+
+Here, find_path function finds the points on the navigation mesh closest to 
+the input positions. So, you need not worry about them not being exactly over 
+the navigation mesh. 
+
+If you find / print the point on the navigation mesh closest to the position, you can 
+do it in the following way:
+
+.. only:: python
+
+   .. code-block:: python
+
+      pos = LPoint3(0, 1, 5)
+      query.nearest_point(pos)
+      print(pos)
+
+.. only:: cpp
+
+   .. code-block:: cpp
+
+      LPoint3 pos = new LPoint3(0, 1, 5);
+      query.nearest_point(pos);
+
+You have the path stored in the 'path' variable, which has array of points joining
+the path. You can use LineSegs to visualize the path as follows:
+
+.. only:: python
+
+   .. code-block:: python
+
+      from panda3d.core import LineSegs
+
+      pathLine = LineSegs()
+      pathLine.set_color(0, 1, 0)
+      pathLine.set_thickness(5)
+      for i in range(len(path)):
+         pathLine.draw_to(path[i])
+
+      lineNode = pathLine.create()
+      lineNodePath = scene.attach_new_node(lineNode)
+
+.. only:: cpp
+
+   .. code-block:: cpp
+
+      #include "lineSegs.h"
+
+      LineSegs pathLine = new LineSegs();
+      pathLine.set_color(0, 1, 0);
+      pathLine.set_thickness(5);
+      for(int i=0 ; i < path.size() ; i++) {
+         pathLine.draw_to(path[i]);
+      }
+
+      GeomNode *lineNode = pathLine.create();
+      NodePath lineNodePath = scene.attach_new_node(lineNode);
+
+Run the Program
+~~~~~~~~~~~~~~~
+
+Go ahead and run the program. You should see this:
+
+.. image:: path1.png
+
+The green lines show the path between the positions.
+
+Using straight path
+~~~~~~~~~~~~~~~~~~~
+
+You can also a different path querying function. Update the code as follows 
+by replacing the definition of 'path' before visualization using LineSegs:
+
+.. only:: python
+
+   .. code-block:: python
+
+      path = query.find_straight_path(pos1, pos2)
+
+.. only:: cpp
+
+   .. code-block:: cpp
+
+      PTA_LVecBase3 path = query.find_straight_path(pos1, pos2);
+
+After running the program, you should see this:
+
+.. image:: path2.png