Geometry#

Classes for defining hull geometry and vessel structure.

Hull#

class Hull(file_path)#

A hull geometry loaded from an STL file.

Parameters:: file_path (str) – Path to the STL file

static from_box(length, breadth, depth)#

Create a box hull.

Parameters:

length (float) – Length of the box in meters
breadth (float) – Breadth of the box in meters
depth (float) – Depth of the box in meters

Returns:

Hull object

Return type:

Hull

get_bounds()#

Returns the bounding box of the hull.

Returns:: (xmin, xmax, ymin, ymax, zmin, zmax)
Return type:: tuple[float, float, float, float, float, float]

thickness: float or None#: The hull plate thickness in meters. If set, it adds volume to the hydrostatic calculations based on the wetted surface area.

num_triangles()#

Returns the number of triangles in the mesh.

Return type:: int

num_vertices()#

Returns the number of vertices in the mesh.

Return type:: int

transform(translation, rotation, pivot)#

Applies a transformation to the hull.

Parameters:

translation – (dx, dy, dz) translation vector
rotation – (rx, ry, rz) rotation angles in degrees
pivot – (px, py, pz) pivot point for rotation

scale(factor)#

Scales the hull uniformly.

Parameters:: factor – Scale factor

scale_xyz(sx, sy, sz)#

Scales the hull non-uniformly along each axis.

Parameters:

sx – Scale factor along X axis
sy – Scale factor along Y axis
sz – Scale factor along Z axis

simplify(target_count)#

Simplifies the hull mesh to a target number of triangles (in-place).

Parameters:: target_count (int) – Target number of triangles

to_simplified(target_count)#

Returns a simplified copy of the hull.

Parameters:: target_count (int) – Target number of triangles
Returns:: Simplified Hull object
Return type:: Hull

export_stl(file_path)#

Exports the hull to an STL file.

Parameters:: file_path – Output file path

get_vertices()#

Returns the vertices of the hull mesh.

Returns:: List of (x, y, z) tuples
Return type:: list[tuple[float, float, float]]

get_faces()#

Returns the faces (triangles) of the hull mesh.

Returns:: List of (i, j, k) indices tuples
Return type:: list[tuple[int, int, int]]

Vessel#

class Vessel(hull)#

A vessel containing one or more hulls, tanks, and silhouettes.

Parameters:: hull (Hull) – The hull geometry

ap: float#: Aft Perpendicular position (x-coordinate).

fp: float#: Forward Perpendicular position (x-coordinate).

lbp: float#: Length Between Perpendiculars.

get_bounds()#: Returns the combined bounding box of all hulls.

compute_contact_surfaces()#

Pre-compute contact surfaces between all hull pairs.

Uses an adaptive distance threshold based on the average cell size in the overlap zone between each hull pair. This makes the detection scale-independent.

Note: This is automatically called when creating a vessel from multiple hulls via from_hulls(). Calling it again will refresh the contact surfaces (e.g. after transforming hulls).

has_contact_surfaces()#

Returns true if contact surfaces have been pre-computed.

Return type:: bool

num_contact_surfaces()#

Returns the number of contact surface pairs found.

Return type:: int

get_contact_surfaces()#

Get all pre-computed contact surfaces.

Returns:: List of ContactSurface objects
Return type:: list[ContactSurface]

clear_contact_surfaces()#: Removes all pre-computed contact surfaces.

get_hull_thickness(index)#

Returns the hull plate thickness for a specific hull by index.

Parameters:: index (int) – Hull index
Returns:: Hull thickness in meters, or None
Return type:: float or None

set_hull_thickness(index, thickness)#

Sets the hull plate thickness for a specific hull by index.

Parameters:

index (int) – Hull index
thickness (float or None) – Hull thickness in meters, or None to remove

num_hulls()#: Returns the number of hulls.

num_tanks()#: Returns the number of tanks.

add_tank(tank)#

Adds a tank to the vessel.

Parameters:: tank (Tank) – Tank to add

get_total_tanks_mass()#: Returns the total mass of all tank fluids in kg.

get_tanks_center_of_gravity()#: Returns the combined CoG of all tank fluids [x, y, z].

add_silhouette(silhouette)#

Adds a silhouette profile to the vessel.

Parameters:: silhouette (Silhouette) – Silhouette to add

num_silhouettes()#

Returns the number of silhouettes.

Return type:: int

has_silhouettes()#

Returns True if any silhouettes are defined.

Return type:: bool

clear_silhouettes()#: Removes all silhouettes from the vessel.

get_total_emerged_area(waterline_z)#

Returns the total emerged area from all silhouettes (m²).

Parameters:: waterline_z (float) – Waterline Z coordinate
Return type:: float

get_combined_emerged_centroid(waterline_z)#

Returns the combined centroid of all emerged areas [x, z].

Parameters:: waterline_z (float) – Waterline Z coordinate
Return type:: list[float]

add_opening(opening)#

Adds a downflooding opening to the vessel.

Parameters:: opening (DownfloodingOpening) – Opening to add

num_openings()#

Returns the number of downflooding openings.

Return type:: int

clear_openings()#: Removes all downflooding openings from the vessel.

get_hulls()#

Get all hulls in the vessel.

Returns:: List of Hull objects
Return type:: list[Hull]

get_tanks()#

Get all tanks in the vessel.

Returns:: List of Tank objects
Return type:: list[Tank]

get_silhouettes()#

Get all silhouettes in the vessel.

Returns:: List of Silhouette objects
Return type:: list[Silhouette]

get_openings()#

Get all downflooding openings in the vessel.

Returns:: List of DownfloodingOpening objects
Return type:: list[DownfloodingOpening]

add_appendage(appendage)#

Add an appendage to the vessel.

Parameters:: appendage (Appendage) – Appendage to add

num_appendages()#

Returns the number of appendages.

Return type:: int

clear_appendages()#: Removes all appendages.

get_appendages()#

Get all appendages.

Return type:: list[Appendage]

get_total_appendage_volume()#

Returns the total appendage volume in m³.

Return type:: float

get_total_appendage_wetted_surface()#

Returns the total appendage wetted surface in m².

Return type:: float

add_deck_edge(deck_edge)#

Add a deck edge to the vessel.

Parameters:: deck_edge (DeckEdge) – Deck edge to add

num_deck_edges()#

Returns the number of deck edges.

Return type:: int

has_deck_edges()#

Returns true if any deck edges are defined.

Return type:: bool

clear_deck_edges()#: Removes all deck edges.

get_deck_edges()#

Get all deck edges.

Return type:: list[DeckEdge]

get_min_freeboard(heel, trim, waterline_z)#

Calculate minimum freeboard across all deck edges.

Parameters:

heel (float) – Heel angle in degrees
trim (float) – Trim angle in degrees
waterline_z (float) – Waterline Z coordinate

Returns:

Minimum freeboard distance in meters, or None if no deck edges

Return type:

float or None

ContactSurface#

class ContactSurface#

A pre-computed contact surface between two hulls safely ignoring overlap internally.

Pre-computed during vessel construction for multi-hull vessels. Avoids expensive O(N×M) face-to-face contact detection at each hydrostatic/stability calculation.

hull_i: int#: Index of the first hull.

hull_j: int#: Index of the second hull.

total_area: float#: Total pre-computed contact area in m².

num_faces_i: int#: Number of contact faces in hull i.

num_faces_j: int#: Number of contact faces in hull j.

get_face_indices_i()#

Returns the face indices of hull i that are in contact.

Return type:: list[int]

get_face_indices_j()#

Returns the face indices of hull j that are in contact.

Return type:: list[int]

Silhouette#

class Silhouette(file_path)#

A 2D silhouette profile in the X-Z plane for wind heeling calculations.

Used for calculating wind heeling moments per IMO 2008 IS Code (MSC.267).

Parameters:: file_path (str) – Path to the geometry file (DXF, VTK, VTP, CSV, TXT)

static from_points(points, name)#

Create a silhouette from a list of (x, z) points.

Parameters:

points (list[tuple[float, float]]) – List of (x, z) tuples defining the contour
name (str) – Silhouette name

Returns:

Silhouette object

Return type:

Silhouette

name: str#: Silhouette name (from filename or user-defined).

num_points()#

Returns the number of points in the contour.

Return type:: int

is_closed()#

Returns True if the contour is closed (first == last point).

Return type:: bool

get_points()#

Returns the points as a list of (x, y, z) tuples.

Return type:: list[tuple[float, float, float]]

get_area()#

Returns the total lateral area (m²).

Return type:: float

get_centroid()#

Returns the centroid [x, z].

Return type:: list[float]

get_bounds()#

Returns the bounding box (x_min, x_max, z_min, z_max).

Return type:: tuple[float, float, float, float]

get_emerged_area(waterline_z)#

Returns the emerged area above waterline (m²).

Parameters:: waterline_z (float) – Waterline Z coordinate
Return type:: float

get_emerged_centroid(waterline_z)#

Returns the centroid of the emerged area [x, z].

Parameters:: waterline_z (float) – Waterline Z coordinate
Return type:: list[float]

OpeningType#

class OpeningType#

Type of opening that can cause downflooding.

static vent()#: Ventilator opening.

static air_pipe()#: Air pipe without automatic closing device.

static hatch()#: Hatch or manhole.

static door()#: Weathertight door (kept open for operation).

static window()#: Non-weathertight window.

static other(name)#

Custom opening type.

Parameters:: name (str) – Opening type name

DownfloodingOpening#

class DownfloodingOpening#

A downflooding opening point or contour for θf calculation.

Per IMO 2008 IS Code, used to determine when non-weathertight openings become submerged during heel.

static from_point(name, position, opening_type)#

Create opening from a single point.

Parameters:

name (str) – Opening name
position (tuple[float, float, float]) – (x, y, z) position in ship coordinates
opening_type (OpeningType) – Type of opening

Returns:

DownfloodingOpening object

Return type:

DownfloodingOpening

static from_contour(name, points, opening_type)#

Create opening from a contour (polyline boundary).

Parameters:

name (str) – Opening name
points (list[tuple[float, float, float]]) – List of (x, y, z) tuples defining the boundary
opening_type (OpeningType) – Type of opening

Returns:

DownfloodingOpening object

Return type:

DownfloodingOpening

static from_file(file_path, default_type, name=None)#

Load openings from a file (DXF or VTK).

If name is provided: - Single opening: sets logic name to name - Multiple openings: sets names to {name}_{i+1}

Parameters:

file_path (str) – Path to the geometry file (DXF, VTK, VTP)
default_type (OpeningType) – Default OpeningType for loaded openings
name (str or None) – Optional base name for loaded openings

name: str#: Opening name.

is_active: bool#: Whether opening is active in calculations.

set_active(active)#

Set opening active state.

Parameters:: active (bool) – True to include in calculations

num_points()#

Returns the number of points defining the opening.

Return type:: int

get_points()#

Returns points as list of (x, y, z) tuples.

Return type:: list[tuple[float, float, float]]

is_submerged(heel, trim, pivot, waterline_z)#

Check if opening is submerged at given conditions.

Parameters:

heel (float) – Heel angle in degrees
trim (float) – Trim angle in degrees
pivot (tuple[float, float, float]) – Rotation pivot (x, y, z)
waterline_z (float) – Waterline Z coordinate

Return type:

bool

Appendage#

class Appendage#

An appendage (additional volume element) attached to the vessel.

Appendages represent volume contributions from items like keels, rudders, bulbous bows, etc. that are not part of the main hull geometry.

static from_point(name, center, volume)#

Create an appendage from a point (fixed volume at position).

Parameters:

name (str) – Appendage name
center (tuple[float, float, float]) – (x, y, z) center position
volume (float) – Volume in m³

Returns:

Appendage object

Return type:

Appendage

static from_file(name, file_path)#

Create an appendage from an STL or VTK file.

Parameters:

name (str) – Appendage name
file_path (str) – Path to the geometry file

Returns:

Appendage object

Return type:

Appendage

static from_box(name, xmin, xmax, ymin, ymax, zmin, zmax)#

Create an appendage from a box (parallelepiped).

Parameters:

name (str) – Appendage name
xmin – Minimum X coordinate
xmax – Maximum X coordinate
ymin – Minimum Y coordinate
ymax – Maximum Y coordinate
zmin – Minimum Z coordinate
zmax – Maximum Z coordinate

Returns:

Appendage object

Return type:

Appendage

static from_cube(name, center, volume)#

Create an appendage from a cube (center and volume).

Parameters:

name (str) – Appendage name
center (tuple[float, float, float]) – (x, y, z) center position
volume (float) – Volume in m³

Returns:

Appendage object

Return type:

Appendage

static from_sphere(name, center, volume)#

Create an appendage from a sphere (center and volume).

Parameters:

name (str) – Appendage name
center (tuple[float, float, float]) – (x, y, z) center position
volume (float) – Volume in m³

Returns:

Appendage object

Return type:

Appendage

name: str#: The appendage name.

volume: float#: Volume in m³.

center: tuple[float, float, float]#: Center of volume (x, y, z) in meters.

wetted_surface: float or None#: Wetted surface area in m², or None if not set.

bounds: tuple[float, float, float, float, float, float] or None#: Returns bounds (xmin, xmax, ymin, ymax, zmin, zmax) or None if not applicable (Point).

geometry_type()#

Returns the geometry type (Point, Mesh, Box, etc.).

Return type:: str

get_mesh_data()#

Returns mesh data (vertices, faces) if geometry is a mesh.

Returns:: Tuple of (vertices, faces), or None if not a mesh
Return type:: tuple[list[tuple[float, float, float]], list[tuple[int, int, int]]] or None

DeckEdge#

class DeckEdgeSide#

Side of the deck edge (Port, Starboard, or Both).

static port()#: Port side.

static starboard()#: Starboard side.

static both()#: Both sides (mirrored).

class DeckEdge#

A deck edge contour (livet) for freeboard calculation.

static from_points(name, points, side)#

Create a deck edge from a list of 3D points.

Parameters:

name (str) – Deck edge name
points (list[tuple[float, float, float]]) – List of (x, y, z) points
side (DeckEdgeSide) – Side of the deck edge

Returns:

DeckEdge object

Return type:

DeckEdge

static from_file(name, file_path)#

Load a deck edge from a DXF or VTK file.

Parameters:

name (str) – Deck edge name
file_path (str) – Path to the geometry file

Returns:

DeckEdge object

Return type:

DeckEdge

name: str#: The deck edge name.

num_points()#

Returns the number of points.

Return type:: int

get_points()#

Returns points as list of (x, y, z) tuples.

Return type:: list[tuple[float, float, float]]

get_side()#

Returns the side as a string.

Return type:: str

get_freeboard(heel, trim, pivot, waterline_z)#

Calculate freeboard at given conditions.

Parameters:

heel (float) – Heel angle in degrees
trim (float) – Trim angle in degrees
pivot (tuple[float, float, float]) – Rotation pivot (x, y, z)
waterline_z (float) – Waterline Z coordinate

Returns:

Minimum freeboard distance in meters

Return type:

float