Initial camera API, improve orbit crosshair sizing (#636)

* Add initial camera API, more consistent orbit crosshair size

* Fix possible race condition, make FOV and near/far planes configurable from URL

* Remove recommended note

* Cleanup pass

Author: brentyi

docs/source/api/handles/camera_handles.rst

@@ -5,3 +5,10 @@ Camera Handles
    :members:
    :undoc-members:
    :inherited-members:
+
+Initial Camera Configuration
+----------------------------
+
+.. autoclass:: viser.InitialCameraConfig
+   :members:
+   :undoc-members:

docs/source/embedded_visualizations.rst

@@ -189,13 +189,54 @@ You can embed this into other webpages using an HTML ``<iframe />`` tag.
 Step 4: Setting the initial camera pose
 -----------------------------------------------
 
-To set the initial camera pose, you can add a ``&logCamera`` parameter to the URL:
+Using Python
+~~~~~~~~~~~~
+
+The easiest way to set the initial camera pose is using :attr:`viser.ViserServer.initial_camera`
+before serializing or calling :meth:`~viser.SceneApi.show`:
+
+.. code-block:: python
+
+   import viser
+
+   server = viser.ViserServer()
+   server.scene.add_box("/box", color=(255, 0, 0), dimensions=(1, 1, 1))
+
+   # Set the initial camera pose.
+   server.initial_camera.position = (2.0, -4.0, 1.0)
+   server.initial_camera.look_at = (0.0, 0.0, 0.0)
+   server.initial_camera.up = (0.0, 0.0, 1.0)
+
+   # The initial camera is included when serializing.
+   data = server.get_scene_serializer().serialize()
+
+This sets the camera pose that will be used when the visualization first loads.
+See :class:`viser.InitialCameraConfig` for all available options including
+``fov``, ``near``, and ``far``.
+
+Using URL Parameters
+~~~~~~~~~~~~~~~~~~~~
+
+You can also override the initial camera pose using URL parameters. This is
+useful for fine-tuning the camera position after export.
+
+To find the camera parameters, add a ``&logCamera`` parameter to the URL:
 
 * ``http://localhost:8000/viser-client/?playbackPath=http://localhost:8000/recordings/recording.viser&logCamera``
 
 Then, open your Javascript console. You should see the camera pose printed
 whenever you move the camera. It should look something like this:
 
-* ``&initialCameraPosition=2.216,-4.233,-0.947&initialCameraLookAt=-0.115,0.346,-0.192&initialCameraUp=0.329,-0.904,0.272``
+* ``&initialCameraPosition=2.216,-4.233,-0.947&initialCameraLookAt=-0.115,0.346,-0.192&initialCameraUp=0.329,-0.904,0.272&initialCameraFov=0.7854&initialCameraNear=0.01&initialCameraFar=1000``
+
+You can then add this string to the URL to set the initial camera pose. URL
+parameters take priority over the Python-configured initial camera.
+
+Available URL parameters:
 
-You can then add this string to the URL to set the initial camera pose.
+* ``initialCameraPosition`` - Camera position as ``x,y,z``
+* ``initialCameraLookAt`` - Look-at target as ``x,y,z``
+* ``initialCameraUp`` - Up direction as ``x,y,z``
+* ``initialCameraFov`` - Field of view in radians
+* ``initialCameraNear`` - Near clipping plane distance
+* ``initialCameraFar`` - Far clipping plane distance

docs/source/interactive_notebooks.ipynb

@@ -38,7 +38,7 @@
   {
    "cell_type": "markdown",
    "metadata": {},
-   "source": "The visualization is interactive with orbit controls and works offline once loaded.\n\nOptional parameters:\n- `height`: Height of the embedded viewer in pixels (default: 400)\n- `dark_mode`: Use dark color scheme (default: False)"
+   "source": "The visualization is interactive with orbit controls and works offline once loaded.\n\nOptional parameters:\n- `height`: Height of the embedded viewer in pixels (default: 400)\n- `dark_mode`: Use dark color scheme (default: False)\n\n## Setting the Initial Camera\n\nUse {attr}`viser.ViserServer.initial_camera` to set the camera pose when the\nvisualization first loads:\n\n```python\nimport viser\n\nserver = viser.ViserServer()\nserver.scene.add_box(\"/box\", color=(255, 0, 0), dimensions=(1, 1, 1))\n\n# Set the initial camera pose.\nserver.initial_camera.position = (3.0, 3.0, 2.0)\nserver.initial_camera.look_at = (0.0, 0.0, 0.0)\n\nserver.scene.show()\n```\n\nAvailable properties: `position`, `look_at`, `up`, `fov`, `near`, `far`. See\n{class}`viser.InitialCameraConfig` for details."
   },
   {
    "cell_type": "markdown",

src/viser/__init__.py

@@ -61,6 +61,7 @@
 from ._scene_handles import TransformControlsHandle as TransformControlsHandle
 from ._viser import CameraHandle as CameraHandle
 from ._viser import ClientHandle as ClientHandle
+from ._viser import InitialCameraConfig as InitialCameraConfig
 from ._viser import ViserServer as ViserServer
 
 __version__ = "1.0.17"

src/viser/_messages.py

@@ -967,41 +967,53 @@ class SetCameraPositionMessage(Message):
     """Server -> client message to set the camera's position."""
 
     position: Tuple[float, float, float]
+    initial: bool = False
+    """If True, this is an initial camera setup that can be overridden by URL params."""
 
 
 @dataclasses.dataclass
 class SetCameraUpDirectionMessage(Message):
     """Server -> client message to set the camera's up direction."""
 
     position: Tuple[float, float, float]
+    initial: bool = False
+    """If True, this is an initial camera setup that can be overridden by URL params."""
 
 
 @dataclasses.dataclass
 class SetCameraLookAtMessage(Message):
     """Server -> client message to set the camera's look-at point."""
 
     look_at: Tuple[float, float, float]
+    initial: bool = False
+    """If True, this is an initial camera setup that can be overridden by URL params."""
 
 
 @dataclasses.dataclass
 class SetCameraNearMessage(Message):
     """Server -> client message to set the camera's near clipping plane."""
 
     near: float
+    initial: bool = False
+    """If True, this is an initial camera setup that can be overridden by URL params."""
 
 
 @dataclasses.dataclass
 class SetCameraFarMessage(Message):
     """Server -> client message to set the camera's far clipping plane."""
 
     far: float
+    initial: bool = False
+    """If True, this is an initial camera setup that can be overridden by URL params."""
 
 
 @dataclasses.dataclass
 class SetCameraFovMessage(Message):
     """Server -> client message to set the camera's field of view."""
 
     fov: float
+    initial: bool = False
+    """If True, this is an initial camera setup that can be overridden by URL params."""
 
 
 @dataclasses.dataclass

src/viser/_viser.py

@@ -29,6 +29,78 @@
 from .infra._infra import StateSerializer
 
 
+@dataclasses.dataclass
+class InitialCameraConfig:
+    """Configuration for the initial camera pose.
+
+    Accessed via :attr:`ViserServer.initial_camera`. Values set here are
+    applied to new client connections and serialized scenes.
+
+    The API is designed to match :class:`CameraHandle`, which is used for
+    per-client camera control.
+    """
+
+    position: tuple[float, float, float] | npt.NDArray[np.floating] | None = None
+    """Camera position in world coordinates."""
+
+    look_at: tuple[float, float, float] | npt.NDArray[np.floating] | None = None
+    """Point the camera looks at in world coordinates."""
+
+    up: tuple[float, float, float] | npt.NDArray[np.floating] | None = None
+    """Camera up direction."""
+
+    fov: float | None = None
+    """Vertical field of view in radians."""
+
+    near: float | None = None
+    """Near clipping plane distance."""
+
+    far: float | None = None
+    """Far clipping plane distance."""
+
+    def _get_messages(self) -> list[_messages.Message]:
+        """Get camera messages for all non-None fields.
+
+        Messages are marked with initial=True so the client can skip them
+        if URL parameters were provided.
+        """
+        messages: list[_messages.Message] = []
+        if self.position is not None:
+            messages.append(
+                _messages.SetCameraPositionMessage(
+                    cast_vector(self.position, 3),
+                    initial=True,
+                )
+            )
+        if self.look_at is not None:
+            messages.append(
+                _messages.SetCameraLookAtMessage(
+                    cast_vector(self.look_at, 3),
+                    initial=True,
+                )
+            )
+        if self.up is not None:
+            messages.append(
+                _messages.SetCameraUpDirectionMessage(
+                    cast_vector(self.up, 3),
+                    initial=True,
+                )
+            )
+        if self.fov is not None:
+            messages.append(
+                _messages.SetCameraFovMessage(float(self.fov), initial=True)
+            )
+        if self.near is not None:
+            messages.append(
+                _messages.SetCameraNearMessage(float(self.near), initial=True)
+            )
+        if self.far is not None:
+            messages.append(
+                _messages.SetCameraFarMessage(float(self.far), initial=True)
+            )
+        return messages
+
+
 @dataclasses.dataclass
 class _CameraHandleState:
     """Information about a client's camera state."""
@@ -639,6 +711,7 @@ def __init__(
 
         _client_autobuild.ensure_client_is_built()
 
+        self._initial_camera = InitialCameraConfig()
         self._connection = server
         self._connected_clients: dict[int, ClientHandle] = {}
         self._client_lock = threading.Lock()
@@ -707,6 +780,10 @@ async def handle_camera_message(
 
             conn.register_handler(_messages.ViewerCameraMessage, handle_camera_message)
 
+            # Send initial camera messages.
+            for msg in self._initial_camera._get_messages():
+                conn.queue_message(msg)
+
         # Remove clients when they disconnect.
         @server.on_client_disconnect
         async def _(conn: infra.WebsockClientConnection) -> None:
@@ -797,6 +874,21 @@ def request_share_url_no_return() -> None:  # To suppress type error.
         self.gui.reset()
         self.gui.set_panel_label(label)
 
+    @property
+    def initial_camera(self) -> InitialCameraConfig:
+        """Configuration for initial camera pose.
+
+        Set these values to control the initial camera position for new
+        clients and serialized/embedded scenes. The API is designed to match
+        :class:`viser.CameraHandle`, which is used for per-client camera control.
+
+        Example usage::
+
+            server.initial_camera.position = (5.0, 5.0, 3.0)
+            server.initial_camera.look_at = (0.0, 0.0, 0.0)
+        """
+        return self._initial_camera
+
     def _run_garbage_collector(self, force: bool = False) -> None:
         """Clean up old messages. This is not elegant; a refactor of our
         message persistence logic will significantly reduce complexity."""
@@ -1105,4 +1197,12 @@ def get_scene_serializer(self) -> StateSerializer:
         # Insert current scene state.
         for message in self._websock_server._broadcast_buffer.message_from_id.values():
             serializer._insert_message(message)
+
+        # Prepend initial camera messages.
+        camera_messages = [
+            (0.0, msg.as_serializable_dict())
+            for msg in self._initial_camera._get_messages()
+        ]
+        serializer._messages = camera_messages + serializer._messages
+
         return serializer

src/viser/client/src/App.tsx

@@ -257,6 +257,35 @@ function ViewerRoot() {
 
     // Global hover state tracking.
     hoveredElementsCount: 0,
+
+    // Initial camera from URL params (if provided).
+    initialCameraFromUrlParams: (() => {
+      // Helper to parse and validate a vector URL param.
+      const parseVec3 = (
+        param: string,
+      ): [number, number, number] | null => {
+        const str = searchParams.get(param);
+        if (str === null) return null;
+        const parts = str.split(",").map(Number);
+        if (parts.length !== 3 || !parts.every(Number.isFinite)) return null;
+        return parts as [number, number, number];
+      };
+      // Helper to parse and validate a scalar URL param.
+      const parseScalar = (param: string): number | null => {
+        const str = searchParams.get(param);
+        if (str === null) return null;
+        const val = Number(str);
+        return Number.isFinite(val) ? val : null;
+      };
+      return {
+        position: parseVec3("initialCameraPosition"),
+        lookAt: parseVec3("initialCameraLookAt"),
+        up: parseVec3("initialCameraUp"),
+        fov: parseScalar("initialCameraFov"),
+        near: parseScalar("initialCameraNear"),
+        far: parseScalar("initialCameraFar"),
+      };
+    })(),
   });
 
   // Create the scene tree state and extract store and actions.