Quick Start Guide
=================

This guide will help you get started with pynavaltoolbox.

Loading a Hull
--------------

The first step is to load a hull geometry from an STL or VTK file:

.. code-block:: python

   from pynavaltoolbox import Hull, Vessel
   from pynavaltoolbox.hydrostatics import HydrostaticsCalculator, VesselVisualizer
   from pynavaltoolbox.stability import StabilityCalculator

   # Load hull from STL file
   hull_geom = Hull("path/to/hull.stl")

   # Create a vessel (single hull)
   vessel = Vessel(hull_geom)

   # Or create a vessel with explicit perpendiculars
   # vessel = Vessel(hull_geom, ap=0.0, fp=142.0)

   # Get vessel bounding box
   bounds = vessel.get_bounds()  # (xmin, xmax, ymin, ymax, zmin, zmax)
   print(f"Length: {bounds[1] - bounds[0]:.2f} m")

Transforming the Hull
---------------------

You can apply transformations to the hull geometry:

.. code-block:: python

   # Scale uniformly (applies to hull geometry)
   hull_geom.scale(factor=1.5)

   # Scale to target dimensions
   hull_geom.scale(target_bounds=(0, 150, -15, 15, -10, 10))

   # Apply rotation (heel, pitch, yaw in degrees)
   hull_geom.transform(rotation=(5.0, 0.0, 0.0))

   # Simplify mesh for faster calculations
   hull_geom.simplify(target_reduction=0.5)  # Remove 50% of polygons

Calculating Hydrostatics
------------------------

Use the :class:`~pynavaltoolbox.hydrostatics.HydrostaticsCalculator` to compute
hydrostatic properties:

.. code-block:: python

   from pynavaltoolbox.hydrostatics import HydrostaticsCalculator

   # Calculator with 12mm shell thickness
   calc = HydrostaticsCalculator(
       vessel,
       water_density=1025.0,
       shell_thickness=0.012
   )

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

   # Access hydrostatic properties
   print(f"Displacement: {state.displacement_mass:.0f} kg")
   print(f"Displacement Volume: {state.displacement_volume:.2f} m³")
   print(f"LCB: {state.lcb:.2f} m")
   print(f"TCB: {state.tcb:.2f} m")
   print(f"KB (VCB): {state.vcb:.2f} m")
   print(f"KMt: {state.kmt:.2f} m")
   print(f"KMl: {state.kml:.2f} m")
   print(f"Waterplane Area: {state.waterplane_area:.2f} m²")
   print(f"LWL: {state.lwl:.2f} m")
   print(f"BWL: {state.bwl:.2f} m")

Finding Equilibrium
-------------------

Find the equilibrium draft and trim for a given displacement and center of gravity:

.. code-block:: python

   # Find equilibrium for given displacement and CoG
   equilibrium = calc.find_equilibrium(
       displacement_mass=5000000.0,  # kg
       center_of_gravity=(70.0, 0.0, 10.0)  # LCG, TCG, VCG in meters
   )

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

Calculating Stability Curves
----------------------------

Use the :class:`~pynavaltoolbox.stability.StabilityCalculator` for stability analysis:

.. code-block:: python

   from pynavaltoolbox.stability import StabilityCalculator

   stability = StabilityCalculator(vessel, water_density=1025.0)

   # Calculate GZ curve (righting lever)
   gz_curve = stability.calculate_gz_curve(
       displacement_mass=5000000.0,
       cog=(70.0, 0.0, 10.0),  # LCG, TCG, VCG
       heels=list(range(0, 91, 5))  # 0° to 90° in 5° steps
   )

   # Analyze the GZ curve
   print(f"Maximum GZ: {gz_curve.get_max_gz():.3f} m")
   print(f"Angle of Max GZ: {gz_curve.get_angle_of_max_gz():.1f}°")
   print(f"Range of Stability: {gz_curve.get_range_of_stability():.1f}°")

   # Access individual points
   for point in gz_curve.points:
       print(f"Heel: {point.heel}°, GZ: {point.gz:.3f} m, Draft: {point.draft:.2f} m")

   # Calculate KN curve (cross curves of stability)
   kn_curve = stability.calculate_kn_curve(
       displacement_mass=5000000.0,
       heels=[0, 10, 20, 30, 45, 60, 75, 90]
   )

Visualizing the Vessel
----------------------

Use the :class:`~pynavaltoolbox.hydrostatics.VesselVisualizer` to create views:

.. code-block:: python

   from pynavaltoolbox.hydrostatics import VesselVisualizer

   visualizer = VesselVisualizer(vessel)

   # Save a screenshot
   visualizer.save_view(
       filename="vessel_iso.png",
       view_type="iso",  # 'iso', 'side', 'front', 'rear', 'top'
       show_waterline=True,
       draft=5.0
   )

   # Interactive 3D view (opens a window)
   visualizer.show()

Next Steps
----------

* Check out the :doc:`tutorials/index` for detailed tutorials
* See the :doc:`api/index` for complete API reference
* Read the :doc:`contributing` guide if you want to contribute