visualization
=============

.. py:module:: visualization


Functions
---------

.. autoapisummary::

   visualization.visualizeOcTree
   visualization.visualizePath
   visualization.visualizeJointTrajectory
   visualization.plotJointTrajectory
   visualization.addPositionPolyline
   visualization.visualizePositionTrace
   visualization.se3_to_viser_wxyz


Module Contents
---------------

.. py:function:: visualizeOcTree(viz, octree_geometry, prefix)

   Helper function to visualize octree geometries on Viser.

   :param viz: The viser visualizer instance.
   :param octree_geometry: the octree geometry object
   :param prefix: the prefix for geometry name


.. py:function:: visualizePath(viz, scene, path, frame_names, max_step_size, color = (100, 0, 0), name = '/path')

   Helper function to visualize a sparse joint path in Cartesian space, using interpolation.

   :param viz: The Viser visualizer instance.
   :param scene: The scene instance.
   :param path: The joint path to visualize.
   :param frame_names: The list of frame names to use for forward kinematics.
   :param max_step_size: The maximum step size between joint configurations when interpolating paths.
   :param color: The color of the rendered path.
   :param name: The name of the path in Viser.


.. py:function:: visualizeJointTrajectory(viz, scene, traj, frame_names, color = (100, 0, 0), name = '/trajectory')

   Helper function to visualize a joint trajectory in Cartesian space.

   :param viz: The Viser visualizer instance.
   :param scene: The scene instance.
   :param traj: The joint trajectory to visualize.
   :param frame_names: The list of frame names to use for forward kinematics.
   :param color: The color of the rendered trajectory.
   :param name: The name of the trajectory in Viser.


.. py:function:: plotJointTrajectory(trajectory, scene, plot_title = 'Joint Trajectory')

   Plot a joint trajectory of positions over time.

   :param trajectory: The trajectory object to visualize.
   :param scene: The Scene object used to get joint information.
   :param plot_title: The title of the plot.

   :returns: The matplotlib figure object. Use ``matplotlib.pyplot.show()`` to display it.


.. py:function:: addPositionPolyline(viz, name, positions, color, line_width)

   Draw a Cartesian position trajectory as straight line segments.

   :param viz: The Viser visualizer instance.
   :param name: The name of the trace in Viser.
   :param positions: Array of xyz positions with shape (N, 3).
   :param color: RGB color tuple.
   :param line_width: Width of the rendered line.


.. py:function:: visualizePositionTrace(viz, positions, trace_name, waypoint_root, trace_color, waypoint_color, line_width = 5.0, waypoint_radius = 0.01, draw_trace = True, draw_waypoints = True, waypoint_stride = 1)

   Visualize a Cartesian position trace and optional waypoint markers.

   :param viz: The Viser visualizer instance.
   :param positions: Array of xyz positions with shape (N, 3).
   :param trace_name: Name of the line trace in Viser.
   :param waypoint_root: Root name for waypoint markers in Viser.
   :param trace_color: RGB color tuple for the trace.
   :param waypoint_color: RGB color tuple for waypoint markers.
   :param line_width: Width of the rendered line.
   :param waypoint_radius: Radius of waypoint marker spheres.
   :param draw_trace: Whether to draw the line trace.
   :param draw_waypoints: Whether to draw waypoint markers.
   :param waypoint_stride: Draw one waypoint marker every this many positions.


.. py:function:: se3_to_viser_wxyz(transform)

   Extract Viser-compatible position and wxyz quaternion from an SE(3) matrix.

   :param transform: 4x4 homogeneous transform.

   :returns: Tuple of ``(position, wxyz)`` as numpy arrays.