Merge pull request #361 from iory/doc

Enhancements to Build Process and Documentation Updates

.readthedocs.yml

@@ -1,8 +1,16 @@
-name: scikit-robot
-type: sphinx
-base: docs/source
-conda:
-  file: docs/rtd_conda.yml
+version: 2
+build:
+  os: "ubuntu-22.04"
+  tools:
+    python: "3.11"
+
+sphinx:
+   configuration: docs/source/conf.py
+   fail_on_warning: true
+
 python:
-  version: 3.7
-  setup_py_install: true
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - all

docs/source/conf.py

@@ -27,7 +27,7 @@
 
 __version__ = pkg_resources.get_distribution('scikit-robot').version
 on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
-tag = 'master'
+tag = 'main'
 
 # -- Project information -----------------------------------------------------
 
@@ -78,7 +78,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = 'en'
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -213,7 +213,7 @@
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {
     'python': ('https://docs.python.org/3/', None),
-    'trimesh': ('https://trimsh.org/', None),
+    'trimesh': ('https://trimesh.org/', None),
     'numpy': ('https://docs.scipy.org/doc/numpy/', None),
 }
 
@@ -250,6 +250,10 @@ def _is_git_root(path):
     return os.path.isdir(os.path.join(path, '.git'))
 
 
+def _is_site_packages(path):
+    return 'site-packages' in path or 'dist-packages' in path
+
+
 _source_root = None
 
 
@@ -260,7 +264,7 @@ def _find_source_root(source_abs_path):
     if _source_root is None:
         dir = os.path.dirname(source_abs_path)
         while True:
-            if _is_egg_directory(dir) or _is_git_root(dir):
+            if _is_egg_directory(dir) or _is_git_root(dir) or _is_site_packages(dir):
                 # Reached the root directory
                 _source_root = dir
                 break

docs/source/reference/index.rst

@@ -14,3 +14,4 @@ API Reference
    interfaces
    sdfs
    planner
+   viewers

docs/source/reference/viewers.rst

@@ -0,0 +1,79 @@
+Viewers
+=======
+
+
+Examples
+========
+
+You can easily try out visualization programs using the examples found in `scikit-robot/examples <https://github.com/iory/scikit-robot/tree/main/examples>`_
+
+.. code-block:: bash
+
+    python robot_models.py --viewer trimesh
+
+
+.. figure:: ../../image/robot_models.jpg
+    :scale: 100%
+    :align: center
+
+
+
+CommandLine Tools
+=================
+
+
+You can easily visualize a URDF by providing it as an argument to the visualize-urdf command.
+
+
+.. code-block:: bash
+
+    visualize-urdf ~/.skrobot/pr2_description/pr2.urdf
+
+
+.. figure:: ../../image/pr2.png
+    :scale: 20%
+    :align: center
+
+
+Viewer classes
+==============
+
+TrimeshSceneViewer
+------------------
+
+**Description:**
+  The ``TrimeshSceneViewer`` is an extension of the ``trimesh.viewer.SceneViewer`` tailored for visualizing 3D scenes using the Trimesh library. It is specifically designed for 3D triangle meshes visualization and manipulation in robotic applications.
+
+**Key Functionalities:**
+
+- **Initialization and Configuration:**
+  Initializes with options for screen resolution and an update interval. It sets up a scene using Trimesh to manage various geometrical entities.
+
+- **Rendering Control:**
+  Manages redraws upon user interactions such as mouse clicks, drags, scrolls, and key presses. It also handles window resizing events to ensure the scene is accurately rendered.
+
+- **Scene Management:**
+  Supports dynamic addition and deletion of geometrical entities. It allows management of links and their associated meshes, enabling real-time updates based on robotic movements.
+
+- **Camera Management:**
+  Facilitates camera positioning and orientation, allowing for customizable views based on specified angles and transformations reflective of the robotic link configurations.
+
+PyrenderViewer
+--------------
+
+**Description:**
+  The ``PyrenderViewer`` utilizes the Pyrender library for advanced 3D rendering, ideal for creating realistic visual simulations. This viewer is particularly suited for complex rendering tasks in robotics, including detailed lighting and shading effects.
+
+**Key Functionalities:**
+
+- **Initialization and Configuration:**
+  The viewer is initialized with specified resolution and rendering flags, creating a scene managed by Pyrender. It supports high-quality rendering features like raymond lighting.
+
+- **Rendering Control:**
+  Handles real-time scene updates triggered by user interactions such as mouse events and keyboard inputs, ensuring the scene remains interactive and up-to-date.
+
+- **Scene Management:**
+  Similar to ``TrimeshSceneViewer``, it allows for the addition and removal of visual meshes linked to robotic models, supporting dynamic updates to the scene as robotic configurations change.
+
+- **Camera Management:**
+  Offers detailed camera setup options, including angle adjustments, distance settings, center positioning, and field of view configuration, providing flexibility in viewing angles for complex scenes.

setup.py

@@ -11,14 +11,14 @@
 from setuptools import setup
 
 
-version = '0.0.38'
+version = '0.0.39'
 
 
 if sys.argv[-1] == 'release':
     # Release via github-actions.
     commands = [
         'git tag v{:s}'.format(version),
-        'git push origin master --tag',
+        'git push origin main --tag',
     ]
     for cmd in commands:
         print('+ {}'.format(cmd))