Visualization Tutorial#

This tutorial demonstrates how to use the interactive 3D visualization capabilities of NavalToolbox.

The visualization module uses Plotly to create interactive HTML files that can be viewed in any web browser.

Setup#

First, we load a hull and create a vessel instance, as usual:

from navaltoolbox import Hull, Vessel, Tank, Silhouette, DownfloodingOpening, OpeningType
from navaltoolbox.visualization import plot_vessel_3d, plot_hydrostatic_condition

# 1. Load Hull
hull = Hull("path/to/dtmb5415.stl")
vessel = Vessel(hull)

Adding Components#

To make the visualization interesting, let’s add some tanks, a silhouette (superstructure), and an opening.

# Add a Fuel Tank
tank = Tank.from_box(
    name="Fuel Tank 1P",
    x_min=50.0, x_max=60.0,
    y_min=2.0, y_max=8.0,
    z_min=0.0, z_max=5.0,
    fluid_density=850.0
)
tank.fill_percent = 50.0 # Partially filled to show fluid surface
vessel.add_tank(tank)

# Add a Silhouette (Wind profile)
# Ideally load from DXF, but here's a manual one for demo consistency
# (Assuming you have a DXF file or points)
# sil = Silhouette("superstructure.dxf")
# vessel.add_silhouette(sil)

# Add a Downflooding Opening
opening = DownfloodingOpening.from_point(
    name="Vent 1",
    position=(75.0, 9.8, 12.0),
    opening_type=OpeningType.vent()
)
vessel.add_opening(opening)

# Add Appendages
# rudder = Appendage.from_point("Rudder", (100, 0, -2), 1.5)
# vessel.add_appendage(rudder)

# Add Deck Edges (Livet)
# deck = DeckEdge.from_points("Main Deck", [...], DeckEdgeSide.both())
# vessel.add_deck_edge(deck)

General Arrangement Plot#

Use plot_vessel_3d() to visualize the vessel and its internal components in the upright condition.

# Create the figure
fig = plot_vessel_3d(
    vessel,
    show_hulls=True,
    show_tanks=True,
    show_silhouettes=True,
    show_openings=True,
    opacity_hull=0.3, # Semi-transparent to see tanks inside
    title="General Arrangement"
)

# Save to HTML
fig.write_html("vessel_ga.html")
# fig.show() # To open immediately in browser

The resulting plot includes:

  • View Controls: Buttons to switch between ISO, STBD (Profile), TOP (Plan), etc.

  • Projection Toggle: Switch between Perspective (realistic) and Orthographic (engineering) views.

  • Hull Opacity Slider: A slider to adjust hull transparency dynamically.

Hydrostatic Condition Plot#

Use plot_hydrostatic_condition() to visualize the vessel floating at a specific draft, trim, and heel. This visualization:

  1. Fixes the waterplane at Z=0.

  2. Rotates and translates the vessel to match the floating condition.

  3. Shows the Center of Gravity (COG).

  4. Shows the fluid level inside tanks, correctly inclined.

# Define floating condition
draft_mid = 6.15
heel = 15.0 # degrees stability test
trim = 1.0  # degrees by stern

# Assume we know the COG position
cog_pos = (70.0, 0.0, 7.5)

# Create the hydrostatic plot
fig_hydro = plot_hydrostatic_condition(
    vessel,
    draft=draft_mid,
    heel=heel,
    trim=trim,
    title=f"Hydrostatic Condition (T={draft_mid}m, Heel={heel}deg)",
    opacity_hull=0.5,
    cog=cog_pos,
    show_axes=True # Set to False for a cleaner look
)

# Save
fig_hydro.write_html("hydrostatics.html")

Features:

  • The Waterplane is visualized as a blue surface at Z=0.

  • In Orthographic Side Views (e.g. STBD), a blue line represents the waterline level.

  • Tanks show the fluid surface parallel to the external waterplane (taking heel/trim into account).

Note

The vessel is transformed (moved/rotated) relative to a fixed world frame where the water surface is always at Z=0. This makes it intuitive to check immersion and downflooding points relative to the water.