234 lines
6.3 KiB
ReStructuredText
234 lines
6.3 KiB
ReStructuredText
Quickstart
|
|
==========
|
|
|
|
This guide will help you get started with NavalToolbox in Python.
|
|
|
|
Loading a Hull
|
|
--------------
|
|
|
|
Load a hull geometry from an STL file:
|
|
|
|
.. code-block:: python
|
|
|
|
from navaltoolbox import Hull
|
|
|
|
# Load hull from STL file
|
|
hull = Hull("ship.stl")
|
|
|
|
# Check hull dimensions
|
|
bounds = hull.get_bounds()
|
|
loa = bounds[1] - bounds[0] # Length overall
|
|
boa = bounds[3] - bounds[2] # Beam overall
|
|
|
|
print(f"LOA: {loa:.2f}m, BOA: {boa:.2f}m")
|
|
print(f"Triangles: {hull.num_triangles()}")
|
|
|
|
Setting Hull Thickness
|
|
----------------------
|
|
|
|
You can assign a plate thickness to the hull, which NavalToolbox uses to automatically add the corresponding volume to the hydrostatic calculations:
|
|
|
|
.. code-block:: python
|
|
|
|
# Set 15mm thickness
|
|
hull.thickness = 0.015
|
|
|
|
Creating a Vessel
|
|
-----------------
|
|
|
|
Wrap the hull in a Vessel container:
|
|
|
|
.. code-block:: python
|
|
|
|
from navaltoolbox import Hull, Vessel
|
|
|
|
hull = Hull("ship.stl")
|
|
vessel = Vessel(hull)
|
|
|
|
# Get perpendiculars (auto-calculated from bounds)
|
|
print(f"AP: {vessel.ap:.2f}m")
|
|
print(f"FP: {vessel.fp:.2f}m")
|
|
print(f"LBP: {vessel.lbp:.2f}m")
|
|
|
|
Calculating Hydrostatics
|
|
------------------------
|
|
|
|
Calculate hydrostatic properties at a given draft:
|
|
|
|
.. code-block:: python
|
|
|
|
from navaltoolbox import Hull, Vessel, HydrostaticsCalculator
|
|
|
|
hull = Hull("ship.stl")
|
|
vessel = Vessel(hull)
|
|
calc = HydrostaticsCalculator(vessel, water_density=1025.0)
|
|
|
|
# Calculate at specific draft
|
|
state = calc.from_draft(
|
|
draft=6.0, # meters
|
|
trim=0.0, # degrees
|
|
heel=0.0, # degrees
|
|
vcg=7.5 # VCG for GM calculation
|
|
)
|
|
|
|
print(f"Volume: {state.volume:.1f} m³")
|
|
print(f"Displacement: {state.displacement:.0f} kg")
|
|
print(f"Lwl: {state.lwl:.2f}m")
|
|
print(f"Bwl: {state.bwl:.2f}m")
|
|
print(f"Wetted Surface: {state.wetted_surface_area:.1f}m²")
|
|
print(f"Cb: {state.cb:.3f}")
|
|
print(f"LCB: {state.lcb:.2f}m")
|
|
print(f"VCB: {state.vcb:.2f}m")
|
|
print(f"GMT (corrected): {state.gmt:.3f}m")
|
|
|
|
Calculating GZ Curve
|
|
--------------------
|
|
|
|
Calculate the stability (GZ) curve:
|
|
|
|
.. code-block:: python
|
|
|
|
from navaltoolbox import Hull, Vessel, StabilityCalculator
|
|
|
|
hull = Hull("ship.stl")
|
|
vessel = Vessel(hull)
|
|
calc = StabilityCalculator(vessel, water_density=1025.0)
|
|
|
|
# Define loading condition
|
|
displacement = 8635000 # kg
|
|
cog = (71.67, 0.0, 7.555) # LCG, TCG, VCG
|
|
|
|
# Heel angles to calculate
|
|
heels = [0, 5, 10, 15, 20, 25, 30, 35, 40, 45, 50, 55, 60]
|
|
|
|
# Calculate GZ curve
|
|
curve = calc.gz_curve(displacement, cog, heels)
|
|
|
|
# Print results
|
|
for heel, gz in zip(curve.heels(), curve.values()):
|
|
print(f"Heel {heel:5.1f}°: GZ = {gz:+.3f}m")
|
|
|
|
Complete Stability Analysis
|
|
---------------------------
|
|
|
|
Calculate hydrostatics, GZ curve, and wind data in one call:
|
|
|
|
.. code-block:: python
|
|
|
|
from navaltoolbox import Hull, Vessel, StabilityCalculator, Silhouette, DownfloodingOpening, OpeningType
|
|
|
|
hull = Hull("ship.stl")
|
|
vessel = Vessel(hull)
|
|
|
|
# Optionally add silhouette for wind heeling data
|
|
silhouette = Silhouette.from_points([
|
|
(0, 0), (150, 0), (150, 15), (0, 15), (0, 0)
|
|
], "hull_profile")
|
|
vessel.add_silhouette(silhouette)
|
|
|
|
# Add downflooding opening (e.g., air pipe, ventilator)
|
|
opening = DownfloodingOpening.from_point(
|
|
name="Vent pipe",
|
|
position=(75.0, 9.8, 12.5),
|
|
opening_type=OpeningType.vent()
|
|
)
|
|
vessel.add_opening(opening)
|
|
|
|
calc = StabilityCalculator(vessel, water_density=1025.0)
|
|
|
|
# Complete stability analysis
|
|
result = calc.complete_stability(
|
|
displacement_mass=8635000, # kg
|
|
cog=(71.67, 0.0, 7.555), # LCG, TCG, VCG
|
|
heels=[0, 10, 20, 30, 40, 50, 60] # degrees
|
|
)
|
|
|
|
# Access hydrostatics
|
|
print(f"Draft: {result.hydrostatics.draft:.3f} m")
|
|
print(f"GM0: {result.gm0:.3f} m")
|
|
|
|
# Access GZ curve
|
|
print(f"Max GZ: {result.max_gz:.3f} m at {result.heel_at_max_gz}°")
|
|
|
|
# Access wind data (if silhouettes defined)
|
|
if result.has_wind_data():
|
|
wind = result.wind_data
|
|
print(f"Emerged area: {wind.emerged_area:.1f} m²")
|
|
print(f"Wind lever arm: {wind.wind_lever_arm:.2f} m")
|
|
|
|
Working with Tanks
|
|
------------------
|
|
|
|
Create and manage tanks:
|
|
|
|
.. code-block:: python
|
|
|
|
from navaltoolbox import Tank
|
|
|
|
# Create a box-shaped tank
|
|
tank = Tank.from_box(
|
|
name="Fuel Tank 1",
|
|
x_min=40.0, x_max=60.0, # longitudinal
|
|
y_min=-8.0, y_max=8.0, # transverse
|
|
z_min=0.0, z_max=5.0, # vertical
|
|
fluid_density=850.0 # kg/m³ (fuel oil)
|
|
)
|
|
vessel.add_tank(tank)
|
|
|
|
# Set fill level and permeability
|
|
tank.fill_percent = 75.0
|
|
tank.permeability = 0.95 # Optional: account for internal structure
|
|
|
|
# Get tank properties
|
|
print(f"Total volume: {tank.total_volume:.1f} m³")
|
|
print(f"Fill volume: {tank.fill_volume:.1f} m³")
|
|
print(f"Fluid mass: {tank.fluid_mass:.0f} kg")
|
|
print(f"CoG: {tank.center_of_gravity}")
|
|
print(f"FSM (transverse): {tank.free_surface_moment_t:.1f} m⁴")
|
|
|
|
Working with Silhouettes
|
|
------------------------
|
|
|
|
Create silhouettes for wind heeling calculations:
|
|
|
|
.. code-block:: python
|
|
|
|
from navaltoolbox import Hull, Vessel, Silhouette
|
|
|
|
hull = Hull("ship.stl")
|
|
vessel = Vessel(hull)
|
|
|
|
# Load from DXF file
|
|
hull_profile = Silhouette("hull_profile.dxf")
|
|
|
|
# Or load from VTK file
|
|
superstructure = Silhouette("superstructure.vtk")
|
|
|
|
# Or create from points (x, z coordinates)
|
|
container = Silhouette.from_points([
|
|
(40, 15), (80, 15), (80, 25), (40, 25), (40, 15)
|
|
], "container")
|
|
|
|
# Add to vessel
|
|
vessel.add_silhouette(hull_profile)
|
|
vessel.add_silhouette(superstructure)
|
|
vessel.add_silhouette(container)
|
|
|
|
print(f"Number of silhouettes: {vessel.num_silhouettes()}")
|
|
|
|
# Calculate emerged area at waterline
|
|
waterline_z = 6.15 # meters
|
|
area = vessel.get_total_emerged_area(waterline_z)
|
|
centroid = vessel.get_combined_emerged_centroid(waterline_z)
|
|
|
|
print(f"Emerged area: {area:.1f} m²")
|
|
print(f"Centroid: x={centroid[0]:.1f}m, z={centroid[1]:.1f}m")
|
|
|
|
Next Steps
|
|
----------
|
|
|
|
- See :doc:`../tutorials/hydrostatics` for detailed hydrostatics calculations
|
|
- See :doc:`../tutorials/stability` for complete stability analysis
|
|
- See :doc:`../api/python/index` for full API reference
|
|
|