Setup website with docusaurus (facebookresearch#11)

Summary:
Set up landing page, docs page, and html versions of the ipython notebook tutorials.
Pull Request resolved: fairinternal/pytorch3d#11

Reviewed By: gkioxari

Differential Revision: D19730380

Pulled By: nikhilaravi

fbshipit-source-id: 5df8d3f2ac2f8dce4d51f5d14fc336508c2fd0ea

Author: nikhilaravi

.gitignore

@@ -2,3 +2,16 @@ build/
 dist/
 *.egg-info/
 **/__pycache__/
+
+# Docusaurus site
+website/yarn.lock
+website/build/
+website/i18n/
+website/node_modules/*
+website/npm-debug.log
+
+## Generated for tutorials
+website/_tutorials/
+website/static/files/
+website/pages/tutorials/*
+!website/pages/tutorials/index.js

docs/figs/architecture_overview.png renamed to docs/notes/assets/architecture_overview.png

@@ -1,8 +1,13 @@
+---
+hide_title: true
+sidebar_label: Batching
+---
+
 # Batching
 
 In deep learning, every optimization step operates on multiple input examples for robust training. Thus, efficient batching is crucial. For image inputs, batching is straighforward; N images are resized to the same height and width and stacked as a 4 dimensional tensor of shape `N x 3 x H x W`. For meshes, batching is less straighforward.
 
-<img src="../figs/batch_intro.png" alt="batch_intro" align="middle"/>
+<img src="assets/batch_intro.png" alt="batch_intro" align="middle"/>
 
 ## Batch modes for meshes
 
@@ -12,13 +17,13 @@ Assume you want to construct a batch containing two meshes, with `mesh1 = (v1: V
 * Padded: The padded representation constructs a tensor by padding the extra values. Specifically, `meshes.verts_padded()` returns a tensor of shape `2 x max(V1, V2) x 3` and pads the extra vertices with `0`s. Similarly, `meshes.faces_padded()` returns a tensor of shape `2 x max(F1, F2) x 3` and pads the extra faces with `-1`s.
 * Packed: The packed representation concatenates the examples in the batch into a tensor. In particular, `meshes.verts_packed()` returns a tensor of shape `(V1 + V2) x 3`. Similarly, `meshes.faces_packed()` returns a tensor of shape `(F1 + F2) x 3` for the faces. In the packed mode, auxiliary variables are computed that enable efficient conversion between packed and padded or list modes.
 
-<img src="../figs/batch_modes.gif" alt="batch_modes" height="450" align="middle" />
+<img src="assets/batch_modes.gif" alt="batch_modes" height="450" align="middle" />
 
 ## Use cases for batch modes
 
 The need for different mesh batch modes is inherent to the way pytorch operators are implemented. To fully utilize the optimized pytorch ops, the [Meshes][meshes] data structure allows for efficient conversion between the different batch modes. This is crucial when aiming for a fast and efficient training cycle. An example of this is [Mesh R-CNN][meshrcnn]. Here, in the same forward pass different parts of the network assume different inputs, which are computed by converting between the different batch modes. In particular, [vert_align][vert_align] assumes a *padded* input tensor while immediately after [graph_conv][graphconv] assumes a *packed* input tensor.
 
-<img src="../figs/meshrcnn.png" alt="meshrcnn" width="700" align="middle" />
+<img src="assets/meshrcnn.png" alt="meshrcnn" width="700" align="middle" />
 
 
 [meshes]: https://github.com/facebookresearch/pytorch3d/blob/master/pytorch3d/structures/meshes.py

docs/figs/batch_intro.png renamed to docs/notes/assets/batch_intro.png

@@ -1,3 +1,8 @@
+---
+sidebar_label: Loading from file
+hide_title: true
+---
+
 # Meshes and IO
 
 The Meshes object represents a batch of triangulated meshes, and is central to

docs/figs/batch_modes.gif renamed to docs/notes/assets/batch_modes.gif

@@ -1,4 +1,9 @@
-# Differentiable Rendering
+---
+hide_title: true
+sidebar_label:  Overview
+---
+
+# Rendering Overview
 
 Differentiable rendering is a relatively new and exciting research area in computer vision, bridging the gap between 2D and 3D by allowing 2D image pixels to be related back to 3D properties of a scene.
 
@@ -18,7 +23,7 @@ Our implementation decouples the rasterization and shading steps of rendering. T
 
 ## <u>Get started</u>
 
-To learn about more the implementation and start using the renderer refer to [renderer_getting_started.md](renderer_getting_started.md), which also contains the [architecture overview](../figs/architecture_overview.png) and [coordinate transformation conventions](../figs/transformations_overview.png).
+To learn about more the implementation and start using the renderer refer to [renderer_getting_started.md](renderer_getting_started.md), which also contains the [architecture overview](assets/architecture_overview.png) and [coordinate transformation conventions](assets/transformations_overview.png).
 
 
 ## <u>Key features</u>
@@ -37,7 +42,7 @@ We compared PyTorch3d with SoftRasterizer to measure the effect of both these de
 
 This figure shows how the coarse-to-fine strategy for rasterization results in significant speed up compared to naive rasterization for large image size and large mesh sizes.
 
-<img src="../figs/p3d_naive_vs_coarse.png" width="1000">
+<img src="assets/p3d_naive_vs_coarse.png" width="1000">
 
 
 For small mesh and image sizes, the naive approach is slightly faster. We advise that you understand the data you are using and choose the rasterization setting which suits your performance requirements. It is easy to switch between the naive and coarse-to-fine options by adjusting the `bin_size` value when initializing the [rasterization settings](https://github.com/facebookresearch/pytorch3d/blob/master/pytorch3d/renderer/mesh/rasterizer.py#L26).
@@ -50,7 +55,7 @@ This figure shows the effect of the _combination_ of coarse-to-fine rasterizatio
 
 In the SoftRasterizer implementation, in both the forward and backward pass, there is a loop over every single face in the mesh for every pixel in the image. Therefore, the time for the full forward plus backward pass is ~2x the time for the forward pass. For small mesh and image sizes, the SoftRasterizer approach is slightly faster.
 
-<img src="../figs/p3d_vs_softras.png" width="1000">
+<img src="assets/p3d_vs_softras.png" width="1000">
 
 
 
@@ -66,7 +71,7 @@ We tested with a range of increasingly large meshes and bin sizes.
 
 **Fig 3: PyTorch3d heterogeneous batching compared with SoftRasterizer**
 
-<img src="../figs/fullset_batch_size_16.png" width="700"/>
+<img src="assets/fullset_batch_size_16.png" width="700"/>
 
 This shows that for large meshes and large bin width (i.e. more variation in mesh size in the batch) the heterogeneous batching approach in PyTorch3d is faster than either of the workarounds with SoftRasterizer.
 

docs/figs/fullset_batch_size_16.png renamed to docs/notes/assets/fullset_batch_size_16.png

@@ -1,10 +1,15 @@
+---
+hide_title: true
+sidebar_label: Getting Started
+---
+
 # Renderer Getting Started
 
 ### Architecture Overview
 
 The renderer is designed to be modular, extensible and support batching and gradients for all inputs. The following figure describes all the components of the rendering pipeline.
 
-<img src="../figs/architecture_overview.png" width="1000">
+<img src="assets/architecture_overview.png" width="1000">
 
 ##### Fragments
 
@@ -31,7 +36,7 @@ The differentiable renderer API is experimental and subject to change!.
 
 Rendering requires transformations between several different coordinate frames: world space, view/camera space, NDC space and screen space. At each step it is important to know where the camera is located, how the x,y,z axes are aligned and the possible range of values. The following figure outlines the conventions used PyTorch3d.
 
-<img src="../figs/transformations_overview.png" width="1000">
+<img src="assets/transformations_overview.png" width="1000">
 
 
 
@@ -43,7 +48,7 @@ While we tried to emulate several aspects of OpenGL, the NDC coordinate system i
 
 In OpenGL, the camera at the origin is looking along `-z` axis in camera space, but it is looking along the `+z` axis in NDC space.
 
-<img align="center" src="../figs/opengl_coordframes.png" width="300">
+<img align="center" src="assets/opengl_coordframes.png" width="300">
 
 ---
 ### A simple renderer

docs/figs/meshrcnn.png renamed to docs/notes/assets/meshrcnn.png

@@ -0,0 +1,13 @@
+---
+hide_title: true
+sidebar_label: Why PyTorch3d
+---
+
+
+# Why PyTorch3d
+
+
+Our goal with PyTorch3D is to help accelerate research at the intersection of deep learning and 3D. 3D data is more complex than 2D images and while working on projects such as [Mesh R-CNN](https://github.com/facebookresearch/meshrcnn) and [C3DPO](https://github.com/facebookresearch/c3dpo_nrsfm), we encountered several challenges including 3D data representation, batching, and speed. We have developed many useful operators and abstractions for working on 3D deep learning and want to share this with the community to drive novel research in this area. 
+
+In PyTorch3D we have included efficient 3D operators, heterogeneous batching capabilities, and a modular differentiable rendering API, to equip researchers in this field with a much needed toolkit to implement cutting-edge research with complex 3D inputs.
+

docs/figs/opengl_coordframes.png renamed to docs/notes/assets/opengl_coordframes.png

@@ -11,15 +11,6 @@
     "# Copyright (c) Facebook, Inc. and its affiliates. All rights reserved."
    ]
   },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "<a href=\"https://colab.research.google.com/github/facebookresearch/pytorch3d/blob/master/docs/tutorials/bundle_adjustment.ipynb\">\n",
-    "  <img align=\"left\" src=\"https://colab.research.google.com/assets/colab-badge.svg\" alt=\"Open In Colab\"/>\n",
-    "</a>"
-   ]
-  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -40,10 +31,10 @@
     "where $d(g_i, g_j)$ is a suitable metric that compares the extrinsics of cameras $g_i$ and $g_j$. \n",
     "\n",
     "Visually, the problem can be described as follows. The picture below depicts the situation at the beginning of our optimization. The ground truth cameras are plotted in green while the randomly initialized estimated cameras are plotted in blue:\n",
-    "![Initialization](./data/bundle_adjustment_initialization.png)\n",
+    "![Initialization](data/bundle_adjustment_initialization.png)\n",
     "\n",
     "Our optimization seeks to align the estimated (blue) cameras with the ground truth (green) cameras, by minimizing the discrepancies between pairs of relative cameras. Thus, the solution to the problem should look as follows:\n",
-    "![Solution](./data/bundle_adjustment_final.png)\n",
+    "![Solution](data/bundle_adjustment_final.png)\n",
     "\n",
     "In practice, the camera extrinsics $g_{ij}$ and $g_i$ are represented using objects from the `SfMPerspectiveCameras` class initialized with the corresponding rotation and translation matrices `R_absolute` and `T_absolute` that define the extrinsic parameters $g = (R, T); R \\in SO(3); T \\in \\mathbb{R}^3$. In order to ensure that `R_absolute` is a valid rotation matrix, we represent it using an exponential map (implemented with `so3_exponential_map`) of the axis-angle representation of the rotation `log_R_absolute`.\n",
     "\n",
@@ -421,9 +412,9 @@
   },
   "file_extension": ".py",
   "kernelspec": {
-   "display_name": "pytorch3d (local)",
+   "display_name": "p3d_dev7",
    "language": "python",
-   "name": "pytorch3d_local"
+   "name": "p3d_dev7"
   },
   "language_info": {
    "codemirror_mode": {
@@ -435,7 +426,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.7.5+"
+   "version": "3.7.6"
   },
   "mimetype": "text/x-python",
   "name": "python",

docs/figs/p3d_naive_vs_coarse.png renamed to docs/notes/assets/p3d_naive_vs_coarse.png

@@ -0,0 +1,60 @@
+#!/bin/bash
+# Copyright (c) Facebook, Inc. and its affiliates.
+
+# run this script from the project root using `./scripts/build_docs.sh`
+
+usage() {
+  echo "Usage: $0 [-b]"
+  echo ""
+  echo "Build PyTorch3D documentation."
+  echo ""
+  echo "  -b   Build static version of documentation (otherwise start server)"
+  echo ""
+  exit 1
+}
+
+BUILD_STATIC=false
+
+while getopts 'hb' flag; do
+  case "${flag}" in
+    h)
+      usage
+      ;;
+    b)
+      BUILD_STATIC=true
+      ;;
+    *)
+      usage
+      ;;
+  esac
+done
+
+
+echo "-----------------------------------"
+echo "Building PyTorch3d Docusaurus site"
+echo "-----------------------------------"
+cd website || exit
+yarn
+cd ..
+
+echo "-----------------------------------"
+echo "Generating tutorials"
+echo "-----------------------------------"
+cwd=$(pwd)
+mkdir -p "website/_tutorials"
+mkdir -p "website/static/files"
+python scripts/parse_tutorials.py --repo_dir "${cwd}"
+
+cd website || exit
+
+if [[ $BUILD_STATIC == true ]]; then
+  echo "-----------------------------------"
+  echo "Building static site"
+  echo "-----------------------------------"
+  yarn build
+else
+  echo "-----------------------------------"
+  echo "Starting local server"
+  echo "-----------------------------------"
+  yarn start
+fi

docs/figs/p3d_vs_softras.png renamed to docs/notes/assets/p3d_vs_softras.png

@@ -0,0 +1,111 @@
+#!/usr/bin/env python3
+# Copyright (c) Facebook, Inc. and its affiliates.
+
+import argparse
+import json
+import os
+
+import nbformat
+from bs4 import BeautifulSoup
+from nbconvert import HTMLExporter, ScriptExporter
+
+
+TEMPLATE = """const CWD = process.cwd();
+
+const React = require('react');
+const Tutorial = require(`${{CWD}}/core/Tutorial.js`);
+
+class TutorialPage extends React.Component {{
+  render() {{
+      const {{config: siteConfig}} = this.props;
+      const {{baseUrl}} = siteConfig;
+      return <Tutorial baseUrl={{baseUrl}} tutorialID="{}"/>;
+  }}
+}}
+
+module.exports = TutorialPage;
+
+"""
+
+JS_SCRIPTS = """
+<script
+  src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.1.10/require.min.js">
+</script>
+<script
+  src="https://cdnjs.cloudflare.com/ajax/libs/jquery/2.0.3/jquery.min.js">
+</script>
+"""  # noqa: E501
+
+
+def gen_tutorials(repo_dir: str) -> None:
+    """Generate HTML tutorials for PyTorch3d Docusaurus site from Jupyter notebooks.
+
+    Also create ipynb and py versions of tutorial in Docusaurus site for
+    download.
+    """
+    with open(os.path.join(repo_dir, "website", "tutorials.json"), "r") as infile:
+        tutorial_config = json.loads(infile.read())
+
+    tutorial_ids = {x["id"] for v in tutorial_config.values() for x in v}
+
+    for tid in tutorial_ids:
+        print("Generating {} tutorial".format(tid))
+
+        # convert notebook to HTML
+        ipynb_in_path = os.path.join(repo_dir, "docs", "tutorials", "{}.ipynb".format(tid))
+        with open(ipynb_in_path, "r") as infile:
+            nb_str = infile.read()
+            nb = nbformat.reads(nb_str, nbformat.NO_CONVERT)
+
+        # displayname is absent from notebook metadata
+        nb["metadata"]["kernelspec"]["display_name"] = "python3"
+
+        exporter = HTMLExporter()
+        html, meta = exporter.from_notebook_node(nb)
+
+        # pull out html div for notebook
+        soup = BeautifulSoup(html, "html.parser")
+        nb_meat = soup.find("div", {"id": "notebook-container"})
+        del nb_meat.attrs["id"]
+        nb_meat.attrs["class"] = ["notebook"]
+        html_out = JS_SCRIPTS + str(nb_meat)
+
+        # generate html file
+        html_out_path = os.path.join(
+            repo_dir, "website", "_tutorials", "{}.html".format(tid)
+        )
+        with open(html_out_path, "w") as html_outfile:
+            html_outfile.write(html_out)
+
+        # generate JS file
+        script = TEMPLATE.format(tid)
+        js_out_path = os.path.join(
+            repo_dir, "website", "pages", "tutorials", "{}.js".format(tid)
+        )
+        with open(js_out_path, "w") as js_outfile:
+            js_outfile.write(script)
+
+        # output tutorial in both ipynb & py form
+        ipynb_out_path = os.path.join(
+            repo_dir, "website", "static", "files", "{}.ipynb".format(tid)
+        )
+        with open(ipynb_out_path, "w") as ipynb_outfile:
+            ipynb_outfile.write(nb_str)
+        exporter = ScriptExporter()
+        script, meta = exporter.from_notebook_node(nb)
+        py_out_path = os.path.join(
+            repo_dir, "website", "static", "files", "{}.py".format(tid)
+        )
+        with open(py_out_path, "w") as py_outfile:
+            py_outfile.write(script)
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(
+        description="Generate JS, HTML, ipynb, and py files for tutorials."
+    )
+    parser.add_argument(
+        "--repo_dir", metavar="path", required=True, help="Pytorch3D repo directory."
+    )
+    args = parser.parse_args()
+    gen_tutorials(args.repo_dir)