.. pyNavalToolbox documentation master file

pyNavalToolbox Documentation
============================

.. image:: https://img.shields.io/badge/python-3.8+-blue.svg
   :target: https://www.python.org/downloads/
   :alt: Python Version

.. image:: https://img.shields.io/badge/License-AGPL%20v3-blue.svg
   :target: https://www.gnu.org/licenses/agpl-3.0
   :alt: License: AGPL v3

Welcome to pyNavalToolbox's documentation!

**pyNavalToolbox** is a Python package for naval engineering tools and utilities,
providing hydrostatic and stability calculations for ship hulls.

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   installation
   quickstart
   tutorials/index
   api/index
   contributing

Overview
--------

pyNavalToolbox provides a comprehensive set of tools for naval architecture
and marine engineering applications. The package enables:

* Loading and manipulating hull geometries from STL and VTK files
* Computing hydrostatic properties (displacement, centers, metacentric heights)
* Calculating stability curves (GZ and KN curves)
* Visualizing hull geometries with waterplane

Features
--------

* **Hull Geometry Management**: Load, transform, scale, and export hull meshes
* **Hydrostatic Calculations**: Displacement, buoyancy centers, waterplane properties, metacentric radii
* **Stability Analysis**: GZ curves, KN curves (cross curves of stability)
* **Equilibrium Solver**: Find equilibrium draft and trim for a given loading condition
* **Visualization**: Save hull views and interactive 3D visualization
* **Type hints** for better IDE support
* **NumPy-style docstrings** for comprehensive documentation

Quick Example
-------------

.. code-block:: python

   from pynavaltoolbox import Hull
   from pynavaltoolbox.hydrostatics import HydrostaticsCalculator
   from pynavaltoolbox.stability import StabilityCalculator

   # Load a hull geometry
   hull = Hull("path/to/hull.stl")

   # Calculate hydrostatics at a specific draft
   hydro = HydrostaticsCalculator(hull)
   state = hydro.calculate_at_draft(draft=5.0, trim=0, heel=0)

   print(f"Displacement: {state.displacement_mass:.0f} kg")
   print(f"LCB: {state.lcb:.2f} m")
   print(f"KMt: {state.kmt:.2f} m")

   # Calculate GZ curve
   stability = StabilityCalculator(hull)
   gz_curve = stability.calculate_gz_curve(
       displacement_mass=state.displacement_mass,
       cog=(state.lcb, 0.0, 6.0),  # LCG, TCG, VCG
       heels=list(range(0, 91, 5))
   )

   print(f"Max GZ: {gz_curve.get_max_gz():.2f} m at {gz_curve.get_angle_of_max_gz():.0f}°")

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`