geo3d.visualization.utils
=========================

.. py:module:: geo3d.visualization.utils

.. autoapi-nested-parse::

   Utility helpers for Open3D visualization workflows.



Functions
---------

.. autoapisummary::

   geo3d.visualization.utils.validate_colors
   geo3d.visualization.utils.apply_colors
   geo3d.visualization.utils.compute_default_colors
   geo3d.visualization.utils.to_point_cloud
   geo3d.visualization.utils.compute_label_position
   geo3d.visualization.utils.serialize_geometries
   geo3d.visualization.utils.deserialize_geometries


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

.. py:function:: validate_colors(points: numpy.ndarray, colors: numpy.ndarray | None) -> None

   Validate that a color array matches the given point count.

   :param points: Points array used for visualization.
   :param colors: RGB colors to apply to each point.

   :raises ValueError: If the number of colors does not match the number of points or
       if the colors array does not have shape (N, 3).


.. py:function:: apply_colors(pcd: open3d.geometry.PointCloud, colors: numpy.ndarray | None) -> None

   Apply RGB colors to an Open3D point cloud.

   :param pcd: Open3D PointCloud to color.
   :param colors: RGB color values for each point.


.. py:function:: compute_default_colors(pcd_array: numpy.ndarray, xyz: numpy.ndarray, mode: str = 'z', colormap: str = 'jet') -> numpy.typing.NDArray[numpy.float32]

   Compute default point colors from point cloud data.

   :param pcd_array: Structured numpy array representing the point cloud.
   :param xyz: Extracted XYZ coordinates.
   :param mode: Color mode to compute ("z", "intensity", "classification").
   :param colormap: Matplotlib colormap name.

   :returns: RGB colors as a float32 array of shape (N, 3).

   :raises ValueError: If the requested mode is unknown or required fields are missing.


.. py:function:: to_point_cloud(points: numpy.ndarray, colors: numpy.ndarray | None = None) -> open3d.geometry.PointCloud

   Convert raw points and colors into an Open3D point cloud.

   :param points: Nx3 coordinate array.
   :param colors: Optional per-point RGB values.

   :returns: An Open3D PointCloud instance.


.. py:function:: compute_label_position(geometries: list[open3d.geometry.PointCloud]) -> numpy.typing.NDArray[numpy.float32]

   Compute a label placement position above the combined geometries.

   :param geometries: List of Open3D geometries.

   :returns: A 3D point suitable for placing an on-screen label.


.. py:function:: serialize_geometries(geometries: list[open3d.geometry.PointCloud]) -> list[dict]

   Convert Open3D geometries into serializable dictionaries.

   :param geometries: List of Open3D PointCloud geometries.

   :returns: A list of dictionaries containing points and optional colors.


.. py:function:: deserialize_geometries(data: list[dict]) -> list[open3d.geometry.PointCloud]

   Create Open3D PointCloud geometries from serialized data.

   :param data: Serialized geometry dictionaries.

   :returns: List of reconstructed Open3D PointCloud objects.