Hydrostatics Module
===================

The Hydrostatics module provides tools for calculating hydrostatic properties
of hull geometries, including displacement, buoyancy centers, waterplane
properties, and metacentric heights.

Main Classes
------------

HydrostaticsCalculator
~~~~~~~~~~~~~~~~~~~~~~

.. autoclass:: pynavaltoolbox.hydrostatics.HydrostaticsCalculator
   :members:
   :undoc-members:
   :show-inheritance:
   :special-members: __init__

HydrostaticState
~~~~~~~~~~~~~~~~

.. autoclass:: pynavaltoolbox.hydrostatics.HydrostaticState
   :members:
   :undoc-members:
   :show-inheritance:

VesselVisualizer
~~~~~~~~~~~~~~~~

.. autoclass:: pynavaltoolbox.hydrostatics.VesselVisualizer
   :members:
   :undoc-members:
   :show-inheritance:
   :special-members: __init__

Utility Functions
-----------------

The ``tools`` submodule provides low-level utility functions:

.. automodule:: pynavaltoolbox.hydrostatics.tools
   :members:
   :undoc-members:

Example Usage
-------------

Calculating Hydrostatics at a Draft
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: python

   from pynavaltoolbox import Hull, Vessel
   from pynavaltoolbox.hydrostatics import HydrostaticsCalculator

   hull_geom = Hull("hull.stl")
   vessel = Vessel(hull_geom)
   
   calc = HydrostaticsCalculator(vessel, water_density=1025.0)

   # Calculate at specific draft
   state = calc.calculate_at_draft(draft=5.0, trim=0, heel=0)

   print(f"Displacement: {state.displacement_mass:.0f} kg")
   print(f"Volume: {state.displacement_volume:.2f} m³")
   print(f"LCB: {state.lcb:.2f} m")
   print(f"KB: {state.vcb:.2f} m")
   print(f"KMt: {state.kmt:.2f} m")
   print(f"BMt: {state.bmt:.2f} m")

Finding Equilibrium
~~~~~~~~~~~~~~~~~~~

.. code-block:: python

   # Find equilibrium for given displacement and CoG
   equilibrium = calc.find_equilibrium(
       displacement_mass=5000000.0,
       center_of_gravity=(70.0, 0.0, 10.0),
       initial_draft=5.0  # Optional starting guess
   )

   print(f"Draft: {equilibrium.draft:.2f} m")
   print(f"Trim: {equilibrium.trim:.2f}°")

Visualizing the Vessel
~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: python

   from pynavaltoolbox.hydrostatics import VesselVisualizer

   visualizer = VesselVisualizer(vessel)

   # Save images from different views
   visualizer.save_view("vessel_side.png", view_type="side", draft=5.0)
   visualizer.save_view("vessel_iso.png", view_type="iso", draft=5.0)

   # Interactive visualization
   visualizer.show()