docs and log

CHANGELOG.md

@@ -9,52 +9,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-### Changed
-
-### Removed
-
-
-## [0.2.4] 2024-01-27
-
-### Added
-
-### Changed
-
-### Removed
-
-
-## [0.2.3] 2024-01-27
-
-### Added
-
-### Changed
-
-### Removed
-
-
-## [0.2.2] 2024-01-27
-
-### Added
-
-### Changed
-
-### Removed
-
-
-## [0.2.1] 2024-01-27
-
-### Added
-
-### Changed
-
-### Removed
-
-
-## [0.2.0] 2024-01-26
-
-### Added
+* `compas_notebook.conversions.color_to_threejs`.
+* `compas_notebook.conversions.box_to_threejs`.
+* `compas_notebook.conversions.cone_to_threejs`.
+* `compas_notebook.conversions.cylinder_to_threejs`.
+* `compas_notebook.conversions.polyhedron_to_threejs`.
+* `compas_notebook.conversions.sphere_to_threejs`.
+* `compas_notebook.conversions.torus_to_threejs`.
+* `compas_notebook.scene.BoxObject`.
+* `compas_notebook.scene.ConeObject`.
+* `compas_notebook.scene.CylinderObject`.
+* `compas_notebook.scene.MeshObject`.
+* `compas_notebook.scene.PolyhedronObject`.
+* `compas_notebook.scene.SphereObject`.
+* `compas_notebook.scene.TorusObject`.
+* `compas_notebook.viewer.Viewer`.
 
 ### Changed
 
 ### Removed
-

docs/conf.py

@@ -32,6 +32,7 @@
 
 extensions = sphinx_compas2_theme.default_extensions
 extensions.remove("sphinx.ext.linkcode")
+extensions.append("nbsphinx")
 
 # numpydoc options
 

docs/examples.rst

@@ -2,9 +2,19 @@
 Examples
 ********************************************************************************
 
-.. toctree::
-   :maxdepth: 1
-   :titlesonly:
-   :glob:
+There are example notebooks in the ``notebooks`` directory of the repo.
+To run the notebooks you need to clone the repo and install the package requirements.
 
-   examples/*
+.. code-block:: bash
+
+    $ git clone https://github.com/compas-dev/compas_notebook.git
+    $ cd compas_notebook
+    $ pip install -r requirements-dev.txt
+
+
+Notebooks can be used directly in VS Code, or in the browser using Jupyter.
+To start the Jupyter server, run the following command in a terminal
+
+.. code-block:: bash
+
+    $ jupyter notebook

docs/index.rst

@@ -6,24 +6,24 @@ compas_notebook
 
 Notebook visualization backend for COMPAS using pythreejs
 
-.. .. figure:: /_images/
-     :figclass: figure
-     :class: figure-img img-fluid
+.. figure:: /_images/compas_notebook.png
+    :figclass: figure
+    :class: figure-img img-fluid
 
 
 Table of Contents
 =================
 
 .. toctree::
-   :maxdepth: 3
-   :titlesonly:
-
-   Introduction <self>
-   installation
-   tutorial
-   examples
-   api
-   license
+    :maxdepth: 3
+    :titlesonly:
+
+    Introduction <self>
+    installation
+    tutorial
+    examples
+    api
+    license
 
 
 Indices and tables

docs/tutorial.rst

@@ -4,8 +4,18 @@ Tutorial
 
 The main purpose of :mod:`compas_notebook` is to visualise COMPAS objects in a Jupyter notebook.
 
-Basics
-======
+
+Basic Usage
+===========
+
+Visualization is handled by creating a viewer inside a Jupyter notebook and adding objects to its scene.
+The scene is an instance of :class:`compas.scene.Scene` that is preconfigured for ``context="Notebook"``,
+and works the same way as any other COMPAS scene.
+
+.. note::
+
+    For more information on visualisation with scenes, see ...
+
 
 .. code-block:: python
 
@@ -18,3 +28,104 @@ Basics
     viewer = Viewer()
     viewer.scene.add(mesh)
     viewer.show()
+
+
+Object Colors
+=============
+
+To change the color of an object, specify the color when adding the object to the scene.
+You can use a COMPAS color object, or any of the following color specifications: hex, rgb1, rgb255.
+
+.. code-block:: python
+
+    viewer.scene.add(mesh, color=Color.red())
+    viewer.scene.add(mesh, color='#ff0000')
+    viewer.scene.add(mesh, color=(1.0, 0.0, 0.0))
+    viewer.scene.add(mesh, color=(255, 0, 0))
+
+
+Configuration
+=============
+
+The viewer can be configured to have a certain size and to have a specific background colour.
+
+.. code-block:: python
+
+    viewer = Viewer(width=600, height=400, background='#eeeeee')
+
+The grid can be turned on or off.
+
+.. code-block:: python
+
+    viewer = Viewer(show_grid=False)
+
+
+Viewports
+=========
+
+The viewer supports two viewports: "top" and "perspective".
+The default is "perspective".
+Currently, you can only set the viewport when creating the viewer.
+It cannot be changed afterwards.
+
+.. code-block:: python
+
+    viewer = Viewer(viewport='top')
+
+Note that in the top viewport, rotation controls are disabled.
+
+
+Toolbar
+=======
+
+By default, the viewer has a toolbar with minimal functionality: zoom extents, zoom in, zoom out.
+The toolbar is on by default, but can be turned off.
+
+.. code-block:: python
+
+    viewer = Viewer(show_toolbar=False)
+
+
+Scene Export
+============
+
+Because the scene is an instance of :class:`compas.scene.Scene`, it can be exported to JSON.
+This can be done manually or using the ``save`` button in the viewer.
+
+The scene can be exported by itself
+
+.. code-block:: python
+
+    viewer.scene.to_json("scene.json")
+    compas.json_dump(viewer.scene, "scene.json")
+
+
+or as part of a larger session object.
+
+.. code-block:: python
+
+    compas.json_dump({"scene": viewer.scene, "...": "..."}, "session.json")
+
+
+An exported scene can be loaded into a diferent notebook or visualised in a different visualisation context such as Rhino or Blender.
+
+.. code-block:: python
+
+    # different notebook
+
+    import compas
+    from compas_notebook.viewer import Viewer
+
+    scene = compas.json_load("scene.json")
+    viewer = Viewer(scene=scene)
+    viewer.show()
+
+
+.. code-block:: python
+
+    # Rhino
+
+    import compas
+
+    scene = compas.json_load("scene.json")
+    scene.draw()

notebooks/00_basics.ipynb

@@ -0,0 +1,99 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Basics"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import compas\n",
+    "from compas.datastructures import Mesh\n",
+    "from compas_notebook.viewer import Viewer"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Load a mesh"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "mesh = Mesh.from_obj(compas.get('tubemesh.obj'))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Visualize the mesh"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "PyThreeJS SceneObjects registered.\n"
+     ]
+    },
+    {
+     "data": {
+      "application/vnd.jupyter.widget-view+json": {
+       "model_id": "487a84d762054fd68467db3649b37981",
+       "version_major": 2,
+       "version_minor": 0
+      },
+      "text/plain": [
+       "VBox(children=(HBox(children=(Button(icon='square', layout=Layout(height='32px', width='32px'), style=ButtonSt…"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    }
+   ],
+   "source": [
+    "viewer = Viewer()\n",
+    "viewer.scene.add(mesh, color='#cccccc')\n",
+    "viewer.show()"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.9.10"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}