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:

from pynavaltoolbox import Hull

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

# Load hull with explicit perpendicular positions
hull = Hull("hull.vtk", ap=0.0, fp=142.0)

# Get hull bounding box
bounds = hull.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:

# Scale uniformly
hull.scale(factor=1.5)

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

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

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

Calculating Hydrostatics

Use the HydrostaticsCalculator to compute hydrostatic properties:

from pynavaltoolbox.hydrostatics import HydrostaticsCalculator

# Create calculator
calc = HydrostaticsCalculator(hull, water_density=1025.0)

# 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:

# 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 StabilityCalculator for stability analysis:

from pynavaltoolbox.stability import StabilityCalculator

stability = StabilityCalculator(hull, 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 Hull

Use the HullVisualizer to create views:

from pynavaltoolbox.hydrostatics import HullVisualizer

visualizer = HullVisualizer(hull)

# Save a screenshot
visualizer.save_view(
    filename="hull_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