Merge pull request #61 from rfahrn/docs6

add  .rst files  and utils

Author: AmitMY

Diff for: docs/examples.rst

@@ -0,0 +1,134 @@
+Examples
+========
+
+Pose Format Conversion with Sirens
+-----------------------------------
+
+The ``pose_to_siren_to_pose.py`` script shows us how to change a 3D pose using something called a Siren neural network.
+
+.. note::
+
+   The function follows these steps:
+   
+   1. Fills missing data in the body with zeros.
+   2. Normalizes the pose distribution.
+   3. Converts the pose using the Siren neural network.
+   4. Constructs the new Pose with the predicted data.
+   5. Unnormalizes the pose distribution.
+
+   Also:  Before you start, ensure you have a `.pose` file/ path. This is the standardized format that stores the 3D pose information. If you don't have one, you might either need to obtain it from a relevant dataset or convert your existing pose data into this format.
+
+Step-by-step Guide:
+~~~~~~~~~~~~~~~~~~~
+
+1. **Preparation**
+
+    Begin by importing the necessary modules:
+
+    .. code-block:: python
+
+       import numpy as np
+       from numpy import ma
+       import pose_format.utils.siren as siren
+       from pose_format import Pose
+       from pose_format.numpy import NumPyPoseBody
+       from pose_format.pose_visualizer import PoseVisualizer
+
+
+2. **Define the Conversion Function**
+
+    The function `pose_to_siren_to_pose` is used to perform the conversion. An you find the overview of the whole function :ref:`overview`
+
+
+    .. code-block:: python
+
+        def pose_to_siren_to_pose(p: Pose, fps=None) -> Pose:
+        """Converts a given Pose object to its Siren representation and back to Pose."""
+
+            # Fills missing values with 0's 
+            p.body.zero_filled()
+
+            # Noralizes
+            mu, std = p.normalize_distribution()
+
+            # Use siren net 
+            net = siren.get_pose_siren(p, total_steps=3000, steps_til_summary=100, learning_rate=1e-4, cuda=True)
+
+            new_fps = fps if fps is not None else p.body.fps
+            coords = siren.PoseDataset.get_coords(time=len(p.body.data) / p.body.fps, fps=new_fps)
+
+            # Get predicitons of new Pose data 
+            pred = net(coords).cpu().numpy()
+
+            # Construct new Body out of predcitions 
+            pose_body = NumPyPoseBody(fps=new_fps, data=ma.array(pred), confidence=np.ones(shape=tuple(pred.shape[:3])))
+            p = Pose(header=p.header, body=pose_body)
+
+            # Revert normalization and give back the pose instance
+            p.unnormalize_distribution(mu, std)
+            return p
+
+
+    The function does the following operations:
+
+    - Fills missing data in the pose body with zeros.
+    - Normalizes the pose distribution.
+    - Uses the Siren neural network to transform the pose.
+    - Constructs a new Pose with the predicted data.
+    - Reverts the normalization on the pose distribution.
+
+3. **Usage**
+
+    After defining the function, you can use it in your main script:
+
+    .. code-block:: python
+
+       if __name__ == "__main__":
+        pose_path = "/home/nlp/amit/PhD/PoseFormat/sample-data/1.pose"  # your own file path to a `.pose` file 
+
+        buffer = open(pose_path, "rb").read()
+        p = Pose.read(buffer)
+        print("Poses loaded")
+
+        p = pose_to_siren_to_pose(p)
+
+        info = p.header.normalization_info(
+            p1=("pose_keypoints_2d", "RShoulder"),
+            p2=("pose_keypoints_2d", "LShoulder")
+        )
+        p.normalize(info, scale_factor=300)
+        p.focus()
+
+        v = PoseVisualizer(p)
+        v.save_video("reconstructed.mp4", v.draw(max_frames=3000))
+
+
+    The main script performs these tasks:
+
+    - Reads the pose data from a file.
+    - Applies the ``pose_to_siren_to_pose`` function to the read pose.
+    - Normalizes and focuses the pose.
+    - Visualizes the converted pose using the ``PoseVisualizer``.
+
+4. **Execution**
+
+    To run the script:
+
+    .. code-block:: bash
+
+       $ python pose_format_converter.py
+
+
+
+The ``pose_format`` combined with Siren neural networks is great to transform and work with 3D pose data.
+By understanding and using the functions and methods provided in this script, you will be able to understand better how to manipulate and visualize 3D poses to suit your own requirements.
+
+
+.. _overview:
+
+Overview of ``pose_to_siren_to_pose.py``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. literalinclude:: ../examples/pose_to_siren_to_pose.py
+   :language: python
+   :linenos:

Diff for: docs/index.rst

@@ -0,0 +1,51 @@
+.. Pose documentation master file, created by
+   sphinx-quickstart on Tue Aug 15 14:09:31 2023.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+
+
+========================================
+Welcome to Pose-Format's documentation!
+========================================
+
+Pose is an innovative toolkit created by :cite:`moryossef2021pose-format` dedicated to the handling, manipulation, and visualization of poses. With support for various file formats and the ability to operate
+with Python especially the :ref:`pose_format` package and JavaScript, Pose provides a comprehensive solution for pose-related tasks.
+
+
+
+
+.. toctree::
+   :maxdepth: 3
+   :caption: Introduction
+
+   readme
+
+.. toctree::
+   :maxdepth: 7
+   :caption: Python Code Documentation
+
+   modules
+   pose_format
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Additional Material
+
+   js_docs
+   examples
+   specs_v01
+
+
+
+References
+----------
+
+.. bibliography:: references.bib
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

Diff for: docs/js_docs.rst

@@ -0,0 +1,8 @@
+JavaScript
+------------------------
+
+.. toctree::
+   :maxdepth: 2
+
+   pose_format_js
+   pose_viewer_js

Diff for: docs/json.rst

@@ -0,0 +1,34 @@
+JSON Files
+==========
+
+package.JSON
+-------------
+
+.. literalinclude:: ../src/js/pose_format/package.json
+   :language: json
+   :linenos:
+   :caption: Description or Title for the JSON file
+
+package-lock.JSON
+-----------------
+.. literalinclude:: ../src/js/pose_format/package-lock.json
+   :language: json
+   :linenos:
+   :caption: Description or Title for the JSON file
+
+tsconfig.JSON
+-------------
+
+.. literalinclude:: ../src/js/pose_format/tsconfig.json
+   :language: json
+   :linenos:
+   :caption: Description or Title for the JSON file
+
+tslint.JSON
+-------------
+
+
+.. literalinclude:: ../src/js/pose_format/tslint.json
+   :language: json
+   :linenos:
+   :caption: Description or Title for the JSON file

Diff for: docs/modules.rst

@@ -0,0 +1,54 @@
+Structure
+=============
+
+The :ref:`pose_format` aims to help users with the pose data management and pose analysis.
+ The toolkit offers many functionalities, from reading and editing to visualizing and testing pose data. It provides a wide range of features for these tasks.
+
+This section gives an brief overview of the main feature structure of the package and its functionalities.
+
+Main Features
+-------------
+
+1. **Reading and Manipulating Pose Data**:
+   
+   * 	`.pose` files ensuring cross-compatibility between popular libraries such as NumPy, PyTorch, and TensorFlow.
+   * The loaded data presents multiple manipulation options including:
+     
+     - Normalizing pose data.
+     - Agumentation of data.
+     - Interpolation of data.
+
+
+2. **Visualization Capabilities**:
+
+   - Methods to visualize raw and processed pose data using `pose_format.pose_visualizer.PoseVisualizer` module.
+   - Includes overlay functions for videos.
+
+
+3. **Package Organization and Components**:
+
+   * Structured with submodules and subpackages serving the purposes:
+
+      - :ref:`pose_format_numpy` for NumPy interactions.
+
+      - :ref:`pose_format_tensorflow`  for TensorFlow functionalities.
+
+      - :ref:`pose_format_torch` for PyTorch-related tools.
+
+      - :ref:`pose_format_third_party` for externals.
+
+      - :ref:`pose_format_utils` for utility tools. 
+
+4. **Testing Suite**:
+
+   - Tests for the reliability of the package and its setups/data can be found in :ref:`tests`.
+
+Tests 
+------
+
+This section illustrates the content of the testing suite and the used data. 
+
+.. toctree::
+   :maxdepth: 4
+
+   tests

Diff for: docs/pose_format.numpy.pose_body.rst

@@ -0,0 +1,7 @@
+pose\_format.numpy.pose\_body module
+====================================
+
+.. automodule:: pose_format.numpy.pose_body
+   :members:
+   :undoc-members:
+   :show-inheritance:

Diff for: docs/pose_format.numpy.representation.distance.rst

@@ -0,0 +1,7 @@
+pose\_format.numpy.representation.distance module
+=================================================
+
+.. automodule:: pose_format.numpy.representation.distance
+   :members:
+   :undoc-members:
+   :show-inheritance:

Diff for: docs/pose_format.numpy.representation.distance_test.rst

@@ -0,0 +1,7 @@
+pose\_format.numpy.representation.distance\_test module
+=======================================================
+
+.. automodule:: pose_format.numpy.representation.distance_test
+   :members:
+   :undoc-members:
+   :show-inheritance:

Diff for: docs/pose_format.numpy.representation.rst

@@ -0,0 +1,10 @@
+pose\_format.numpy.representation package
+=========================================
+
+.. toctree::
+   :maxdepth: 2
+
+   pose_format.numpy.representation.distance
+   pose_format.numpy.representation.distance_test
+
+

Diff for: docs/pose_format.numpy.rst

@@ -0,0 +1,17 @@
+.. _pose_format_numpy:
+
+pose_format.numpy package
+==========================
+
+Integration with the NumPy library.
+
+.. automodule:: pose_format.numpy
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. toctree::
+   :maxdepth: 4
+
+   pose_format.numpy.representation
+   pose_format.numpy.pose_body

Diff for: docs/pose_format.pose.rst

@@ -0,0 +1,7 @@
+pose\_format.pose module
+========================
+
+.. automodule:: pose_format.pose
+   :members:
+   :undoc-members:
+   :show-inheritance:

Diff for: docs/pose_format.pose_body.rst

@@ -0,0 +1,7 @@
+pose\_format.pose\_body module
+==============================
+
+.. automodule:: pose_format.pose_body
+   :members:
+   :undoc-members:
+   :show-inheritance:

Diff for: docs/pose_format.pose_header.rst

@@ -0,0 +1,7 @@
+pose\_format.pose\_header module
+================================
+
+.. automodule:: pose_format.pose_header
+   :members:
+   :undoc-members:
+   :show-inheritance:

Diff for: docs/pose_format.pose_representation.rst

@@ -0,0 +1,7 @@
+pose\_format.pose\_representation module
+========================================
+
+.. automodule:: pose_format.pose_representation
+   :members:
+   :undoc-members:
+   :show-inheritance:

Diff for: docs/pose_format.pose_test.rst

@@ -0,0 +1,7 @@
+pose\_format.pose\_test module
+==============================
+
+.. automodule:: pose_format.pose_test
+   :members:
+   :undoc-members:
+   :show-inheritance:

Diff for: docs/pose_format.pose_visualizer.rst

@@ -0,0 +1,7 @@
+pose\_format.pose\_visualizer module
+====================================
+
+.. automodule:: pose_format.pose_visualizer
+   :members:
+   :undoc-members:
+   :show-inheritance: