API revamp (#214)

* Start API revamp

* URDF wrapper fixes

* Fixes

* Minor fixes, docs

* Caps

* Cleanup

* Add backwards compatibility shims

* Cleanup

* Docs

* Remove mypy, formatting

* Type alias fix

Author: brentyi

.github/workflows/mypy.yml

@@ -6,7 +6,6 @@
 
 <p align="left">
     <img alt="pyright" src="https://github.com/nerfstudio-project/viser/workflows/pyright/badge.svg?branch=main" />
-    <img alt="mypy" src="https://github.com/nerfstudio-project/viser/workflows/mypy/badge.svg?branch=main" />
     <img alt="typescript-compile" src="https://github.com/nerfstudio-project/viser/workflows/typescript-compile/badge.svg?branch=main" />
     <a href="https://pypi.org/project/viser/">
         <img alt="codecov" src="https://img.shields.io/pypi/pyversions/viser" />
@@ -39,19 +38,6 @@ To include example dependencies:
 pip install viser[examples]
 ```
 
-```bash
-# Clone the repository.
-git clone https://github.com/nerfstudio-project/viser.git
-
-# Install the package.
-# You can also install via pip: `pip install viser`.
-cd ./viser
-pip install -e .[examples]
-
-# Run an example.
-python ./examples/02_gui.py
-```
-
 After an example script is running, you can connect by navigating to the printed
 URL (default: `http://localhost:8080`).
 

README.md

@@ -0,0 +1,10 @@
+# Camera Handles
+
+<!-- prettier-ignore-start -->
+
+.. autoclass:: viser.CameraHandle
+   :members:
+   :undoc-members:
+   :inherited-members:
+
+<!-- prettier-ignore-end -->

docs/source/camera_handles.md

@@ -1,19 +1,10 @@
 # Client Handles
 
-A handle is created for each client that connects to a server. Handles can be
-used to communicate with just one client, as well as for reading and writing of
-camera state.
-
 <!-- prettier-ignore-start -->
 
 .. autoclass:: viser.ClientHandle
    :members:
    :undoc-members:
    :inherited-members:
 
-.. autoclass:: viser.CameraHandle
-   :members:
-   :undoc-members:
-   :inherited-members:
-
 <!-- prettier-ignore-end -->

docs/source/client_handles.md

@@ -25,17 +25,17 @@ relative to /tree.
 
         while True:
             # Add some coordinate frames to the scene. These will be visualized in the viewer.
-            server.add_frame(
+            server.scene.add_frame(
                 "/tree",
                 wxyz=(1.0, 0.0, 0.0, 0.0),
                 position=(random.random() * 2.0, 2.0, 0.2),
             )
-            server.add_frame(
+            server.scene.add_frame(
                 "/tree/branch",
                 wxyz=(1.0, 0.0, 0.0, 0.0),
                 position=(random.random() * 2.0, 2.0, 0.2),
             )
-            leaf = server.add_frame(
+            leaf = server.scene.add_frame(
                 "/tree/branch/leaf",
                 wxyz=(1.0, 0.0, 0.0, 0.0),
                 position=(random.random() * 2.0, 2.0, 0.2),

docs/source/examples/00_coordinate_frames.rst

@@ -28,13 +28,13 @@ NeRFs), or images to render as 3D textures.
             server = viser.ViserServer()
 
             # Add a background image.
-            server.set_background_image(
+            server.scene.set_background_image(
                 iio.imread(Path(__file__).parent / "assets/Cal_logo.png"),
                 format="png",
             )
 
             # Add main image.
-            server.add_image(
+            server.scene.add_image(
                 "/img",
                 iio.imread(Path(__file__).parent / "assets/Cal_logo.png"),
                 4.0,
@@ -44,7 +44,7 @@ NeRFs), or images to render as 3D textures.
                 position=(2.0, 2.0, 0.0),
             )
             while True:
-                server.add_image(
+                server.scene.add_image(
                     "/noise",
                     onp.random.randint(
                         0,

docs/source/examples/01_image.rst

@@ -23,14 +23,14 @@ Examples of basic GUI elements that we can create, read from, and write to.
             server = viser.ViserServer()
 
             # Add some common GUI elements: number inputs, sliders, vectors, checkboxes.
-            with server.add_gui_folder("Read-only"):
-                gui_counter = server.add_gui_number(
+            with server.gui.add_folder("Read-only"):
+                gui_counter = server.gui.add_number(
                     "Counter",
                     initial_value=0,
                     disabled=True,
                 )
 
-                gui_slider = server.add_gui_slider(
+                gui_slider = server.gui.add_slider(
                     "Slider",
                     min=0,
                     max=100,
@@ -39,52 +39,52 @@ Examples of basic GUI elements that we can create, read from, and write to.
                     disabled=True,
                 )
 
-            with server.add_gui_folder("Editable"):
-                gui_vector2 = server.add_gui_vector2(
+            with server.gui.add_folder("Editable"):
+                gui_vector2 = server.gui.add_vector2(
                     "Position",
                     initial_value=(0.0, 0.0),
                     step=0.1,
                 )
-                gui_vector3 = server.add_gui_vector3(
+                gui_vector3 = server.gui.add_vector3(
                     "Size",
                     initial_value=(1.0, 1.0, 1.0),
                     step=0.25,
                 )
-                with server.add_gui_folder("Text toggle"):
-                    gui_checkbox_hide = server.add_gui_checkbox(
+                with server.gui.add_folder("Text toggle"):
+                    gui_checkbox_hide = server.gui.add_checkbox(
                         "Hide",
                         initial_value=False,
                     )
-                    gui_text = server.add_gui_text(
+                    gui_text = server.gui.add_text(
                         "Text",
                         initial_value="Hello world",
                     )
-                    gui_button = server.add_gui_button("Button")
-                    gui_checkbox_disable = server.add_gui_checkbox(
+                    gui_button = server.gui.add_button("Button")
+                    gui_checkbox_disable = server.gui.add_checkbox(
                         "Disable",
                         initial_value=False,
                     )
-                    gui_rgb = server.add_gui_rgb(
+                    gui_rgb = server.gui.add_rgb(
                         "Color",
                         initial_value=(255, 255, 0),
                     )
-                    gui_multi_slider = server.add_gui_multi_slider(
+                    gui_multi_slider = server.gui.add_multi_slider(
                         "Multi slider",
                         min=0,
                         max=100,
                         step=1,
                         initial_value=(0, 30, 100),
                         marks=((0, "0"), (50, "5"), (70, "7"), 99),
                     )
-                    gui_slider_positions = server.add_gui_slider(
+                    gui_slider_positions = server.gui.add_slider(
                         "# sliders",
                         min=0,
                         max=10,
                         step=1,
                         initial_value=3,
                         marks=((0, "0"), (5, "5"), (7, "7"), 10),
                     )
-                    gui_upload_button = server.add_gui_upload_button(
+                    gui_upload_button = server.gui.add_upload_button(
                         "Upload", icon=viser.Icon.UPLOAD
                     )
 
@@ -108,7 +108,7 @@ Examples of basic GUI elements that we can create, read from, and write to.
                 # We can set the position of a scene node with `.position`, and read the value
                 # of a gui element with `.value`. Changes are automatically reflected in
                 # connected clients.
-                server.add_point_cloud(
+                server.scene.add_point_cloud(
                     "/point_cloud",
                     points=point_positions * onp.array(gui_vector3.value, dtype=onp.float32),
                     colors=(

docs/source/examples/02_gui.rst

@@ -24,14 +24,14 @@ we get updates.
         def main() -> None:
             server = viser.ViserServer()
 
-            gui_reset_scene = server.add_gui_button("Reset Scene")
+            gui_reset_scene = server.gui.add_button("Reset Scene")
 
-            gui_plane = server.add_gui_dropdown(
+            gui_plane = server.gui.add_dropdown(
                 "Grid plane", ("xz", "xy", "yx", "yz", "zx", "zy")
             )
 
             def update_plane() -> None:
-                server.add_grid(
+                server.scene.add_grid(
                     "/grid",
                     width=10.0,
                     height=20.0,
@@ -42,23 +42,23 @@ we get updates.
 
             gui_plane.on_update(lambda _: update_plane())
 
-            with server.add_gui_folder("Control"):
-                gui_show_frame = server.add_gui_checkbox("Show Frame", initial_value=True)
-                gui_show_everything = server.add_gui_checkbox(
+            with server.gui.add_folder("Control"):
+                gui_show_frame = server.gui.add_checkbox("Show Frame", initial_value=True)
+                gui_show_everything = server.gui.add_checkbox(
                     "Show Everything", initial_value=True
                 )
-                gui_axis = server.add_gui_dropdown("Axis", ("x", "y", "z"))
-                gui_include_z = server.add_gui_checkbox("Z in dropdown", initial_value=True)
+                gui_axis = server.gui.add_dropdown("Axis", ("x", "y", "z"))
+                gui_include_z = server.gui.add_checkbox("Z in dropdown", initial_value=True)
 
                 @gui_include_z.on_update
                 def _(_) -> None:
                     gui_axis.options = ("x", "y", "z") if gui_include_z.value else ("x", "y")
 
-                with server.add_gui_folder("Sliders"):
-                    gui_location = server.add_gui_slider(
+                with server.gui.add_folder("Sliders"):
+                    gui_location = server.gui.add_slider(
                         "Location", min=-5.0, max=5.0, step=0.05, initial_value=0.0
                     )
-                    gui_num_points = server.add_gui_slider(
+                    gui_num_points = server.gui.add_slider(
                         "# Points", min=1000, max=200_000, step=1000, initial_value=10_000
                     )
 
@@ -73,7 +73,7 @@ we get updates.
                 else:
                     assert_never(axis)
 
-                server.add_frame(
+                server.scene.add_frame(
                     "/frame",
                     wxyz=(1.0, 0.0, 0.0, 0.0),
                     position=pos,
@@ -83,7 +83,7 @@ we get updates.
 
             def draw_points() -> None:
                 num_points = gui_num_points.value
-                server.add_point_cloud(
+                server.scene.add_point_cloud(
                     "/frame/point_cloud",
                     points=onp.random.normal(size=(num_points, 3)),
                     colors=onp.random.randint(0, 256, size=(num_points, 3)),
@@ -93,7 +93,9 @@ we get updates.
             # Here, we update the point clouds + frames whenever any of the GUI items are updated.
             gui_show_frame.on_update(lambda _: draw_frame())
             gui_show_everything.on_update(
-                lambda _: server.set_global_scene_node_visibility(gui_show_everything.value)
+                lambda _: server.scene.set_global_scene_node_visibility(
+                    gui_show_everything.value
+                )
             )
             gui_axis.on_update(lambda _: draw_frame())
             gui_location.on_update(lambda _: draw_frame())

docs/source/examples/03_gui_callbacks.rst

@@ -18,7 +18,7 @@ Example showing how we can detect new clients and read camera poses from them.
         import viser
 
         server = viser.ViserServer()
-        server.world_axes.visible = True
+        server.scene.world_axes.visible = True
 
 
         @server.on_client_connect
@@ -31,7 +31,7 @@ Example showing how we can detect new clients and read camera poses from them.
                 print(f"New camera on client {client.client_id}!")
 
             # Show the client ID in the GUI.
-            gui_info = client.add_gui_text("Client ID", initial_value=str(client.client_id))
+            gui_info = client.gui.add_text("Client ID", initial_value=str(client.client_id))
             gui_info.disabled = True
 
 

docs/source/examples/04_camera_poses.rst

@@ -40,8 +40,8 @@ corresponding client automatically.
                 position = rng.uniform(-3.0, 3.0, size=(3,))
 
                 # Create a coordinate frame and label.
-                frame = client.add_frame(f"/frame_{i}", wxyz=wxyz, position=position)
-                client.add_label(f"/frame_{i}/label", text=f"Frame {i}")
+                frame = client.scene.add_frame(f"/frame_{i}", wxyz=wxyz, position=position)
+                client.scene.add_label(f"/frame_{i}/label", text=f"Frame {i}")
 
                 # Move the camera when we click a frame.
                 @frame.on_click

docs/source/examples/05_camera_commands.rst

@@ -30,14 +30,14 @@ Visualize a mesh. To get the demo data, see ``./assets/download_dragon_mesh.sh``
         print(f"Loaded mesh with {vertices.shape} vertices, {faces.shape} faces")
 
         server = viser.ViserServer()
-        server.add_mesh_simple(
+        server.scene.add_mesh_simple(
             name="/simple",
             vertices=vertices,
             faces=faces,
             wxyz=tf.SO3.from_x_radians(onp.pi / 2).wxyz,
             position=(0.0, 0.0, 0.0),
         )
-        server.add_mesh_trimesh(
+        server.scene.add_mesh_trimesh(
             name="/trimesh",
             mesh=mesh.smoothed(),
             wxyz=tf.SO3.from_x_radians(onp.pi / 2).wxyz,