feat: implement interactive 3D visualization using Plotly and update documentation

docs/source/api/python/geometry.rst

@@ -10,7 +10,7 @@ Hull
 
    A hull geometry loaded from an STL file.
 
-    :param file_path: Path to the STL file
+   :param file_path: Path to the STL file
    :type file_path: str
 
    .. py:staticmethod:: from_box(length, breadth, depth)
@@ -65,6 +65,20 @@ Hull
 
       :param file_path: Output file path
 
+   .. py:method:: get_vertices()
+
+      Returns the vertices of the hull mesh.
+
+      :returns: List of (x, y, z) tuples
+      :rtype: list[tuple[float, float, float]]
+
+   .. py:method:: get_faces()
+
+      Returns the faces (triangles) of the hull mesh.
+
+      :returns: List of (i, j, k) indices tuples
+      :rtype: list[tuple[int, int, int]]
+
 Vessel
 ------
 
@@ -173,6 +187,34 @@ Vessel
 
       Removes all downflooding openings from the vessel.
 
+   .. py:method:: get_hulls()
+
+      Get all hulls in the vessel.
+
+      :returns: List of Hull objects
+      :rtype: list[Hull]
+
+   .. py:method:: get_tanks()
+
+      Get all tanks in the vessel.
+
+      :returns: List of Tank objects
+      :rtype: list[Tank]
+
+   .. py:method:: get_silhouettes()
+
+      Get all silhouettes in the vessel.
+
+      :returns: List of Silhouette objects
+      :rtype: list[Silhouette]
+
+   .. py:method:: get_openings()
+
+      Get all downflooding openings in the vessel.
+
+      :returns: List of DownfloodingOpening objects
+      :rtype: list[DownfloodingOpening]
+
 Silhouette
 ----------
 

docs/source/api/python/index.rst

@@ -8,5 +8,6 @@ Python API
    hydrostatics
    stability
    tanks
-   scripting
    plotting
+   visualization
+   scripting

docs/source/api/python/tanks.rst

@@ -98,3 +98,41 @@ Tank
       :type: float
 
       Longitudinal free surface moment (m⁴).
+
+   **Geometry**
+
+   .. py:method:: get_vertices()
+
+      Returns the vertices of the tank shell mesh.
+
+      :returns: List of (x, y, z) tuples
+      :rtype: list[tuple[float, float, float]]
+
+   .. py:method:: get_faces()
+
+      Returns the faces (triangles) of the tank shell mesh.
+
+      :returns: List of (i, j, k) indices tuples
+      :rtype: list[tuple[int, int, int]]
+
+   .. py:method:: get_fluid_vertices(heel=0.0, trim=0.0)
+
+      Returns the vertices of the fluid mesh at specified attitude.
+
+      :param heel: Heel angle in degrees
+      :type heel: float
+      :param trim: Trim angle in degrees
+      :type trim: float
+      :returns: List of (x, y, z) tuples
+      :rtype: list[tuple[float, float, float]]
+
+   .. py:method:: get_fluid_faces(heel=0.0, trim=0.0)
+
+      Returns the faces of the fluid mesh at specified attitude.
+
+      :param heel: Heel angle in degrees
+      :type heel: float
+      :param trim: Trim angle in degrees
+      :type trim: float
+      :returns: List of (i, j, k) indices tuples
+      :rtype: list[tuple[int, int, int]]

docs/source/api/python/visualization.rst

@@ -0,0 +1,69 @@
+Visualization
+=============
+
+Interactive 3D visualization tools using Plotly.
+
+.. py:module:: navaltoolbox.visualization
+
+.. py:function:: plot_vessel_3d(vessel, show_hulls=True, show_tanks=True, show_silhouettes=True, show_openings=True, opacity_hull=0.5, opacity_tank=0.3, title="Vessel Visualization", enable_opacity_slider=True, show_axes=True)
+
+   Create an interactive 3D plot of the vessel using Plotly.
+
+   :param vessel: The vessel to visualize.
+   :type vessel: Vessel
+   :param show_hulls: Whether to show hull meshes.
+   :type show_hulls: bool
+   :param show_tanks: Whether to show tank meshes.
+   :type show_tanks: bool
+   :param show_silhouettes: Whether to show silhouette profiles.
+   :type show_silhouettes: bool
+   :param show_openings: Whether to show downflooding openings.
+   :type show_openings: bool
+   :param opacity_hull: Opacity for hull meshes (0.0 to 1.0).
+   :type opacity_hull: float
+   :param opacity_tank: Opacity for tank meshes (0.0 to 1.0).
+   :type opacity_tank: float
+   :param title: Title of the plot.
+   :type title: str
+   :param enable_opacity_slider: Whether to add a slider to control hull opacity.
+   :type enable_opacity_slider: bool
+   :param show_axes: Whether to show axes, grid, and background.
+   :type show_axes: bool
+   :returns: A Plotly Figure object.
+   :rtype: plotly.graph_objects.Figure
+
+.. py:function:: plot_hydrostatic_condition(vessel, draft, trim=0.0, heel=0.0, show_hulls=True, show_tanks=True, show_silhouettes=True, show_openings=True, opacity_hull=0.5, opacity_tank=0.3, title="Hydrostatic Condition", enable_opacity_slider=True, cog=None, show_axes=True)
+
+   Visualize the vessel at a specific hydrostatic condition (floating in water).
+   The waterplane is fixed at Z=0. The vessel is transformed (translated and rotated) to match the draft, trim, and heel.
+
+   :param vessel: The vessel to visualize.
+   :type vessel: Vessel
+   :param draft: Draft at midship (or reference point) in meters.
+   :type draft: float
+   :param trim: Trim angle in degrees (positive = stern down usually).
+   :type trim: float
+   :param heel: Heel angle in degrees (positive = starboard down usually).
+   :type heel: float
+   :param show_hulls: Whether to show hull meshes.
+   :type show_hulls: bool
+   :param show_tanks: Whether to show tank meshes.
+   :type show_tanks: bool
+   :param show_silhouettes: Whether to show silhouette profiles.
+   :type show_silhouettes: bool
+   :param show_openings: Whether to show downflooding openings.
+   :type show_openings: bool
+   :param opacity_hull: Opacity for hull meshes (0.0 to 1.0).
+   :type opacity_hull: float
+   :param opacity_tank: Opacity for tank meshes (0.0 to 1.0).
+   :type opacity_tank: float
+   :param title: Title of the plot.
+   :type title: str
+   :param enable_opacity_slider: Whether to add a slider to control hull opacity.
+   :type enable_opacity_slider: bool
+   :param cog: Optional Center of Gravity (x, y, z) to display.
+   :type cog: tuple[float, float, float] or None
+   :param show_axes: Whether to show axes, grid, and background.
+   :type show_axes: bool
+   :returns: A Plotly Figure object.
+   :rtype: plotly.graph_objects.Figure