279 lines
8.4 KiB
Markdown
279 lines
8.4 KiB
Markdown
# NavalToolbox
|
|
|
|
High-performance naval architecture library for Python, powered by Rust.
|
|
|
|
[](https://pypi.org/project/navaltoolbox/)
|
|
[](https://www.gnu.org/licenses/agpl-3.0)
|
|
[](https://www.python.org/downloads/)
|
|
|
|
## Overview
|
|
|
|
NavalToolbox provides fast and accurate naval architecture calculations through a Python API, with a high-performance Rust backend that handles the heavy computational work.
|
|
|
|
## Features
|
|
|
|
- ⚓ **Hull Geometry**: Load and manipulate ship hulls from STL/VTK files
|
|
- 🚢 **Multi-hull Support**: Catamarans, trimarans, and arbitrary configurations
|
|
- 📊 **Hydrostatics**: Volume, COB, Waterplane ($A_{wp}$, LCF, $BM_t$, $BM_l$), Free Surface Correction ($GM_{dry}/GM_{wet}$)
|
|
- ⚖️ **Stability Analysis**: GZ curve calculation with automatic trim optimization
|
|
- 🌊 **Downflooding Detection**: Automatic detection of submerged openings
|
|
- 🛢️ **Tank Management**: Fill levels, free surface effects, sounding tables
|
|
- 💨 **Wind Heeling**: Silhouette-based wind calculations (DXF/VTK support)
|
|
- ⚡ **High Performance**: Rust backend with Python convenience
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
pip install navaltoolbox
|
|
```
|
|
|
|
**Requirements:**
|
|
- Python 3.9 or higher
|
|
- No additional dependencies required (all native code included in wheels)
|
|
|
|
## Quick Start
|
|
|
|
### Loading a Hull
|
|
|
|
```python
|
|
from navaltoolbox import Hull
|
|
|
|
# Load hull from STL file
|
|
hull = Hull("ship.stl")
|
|
|
|
# Get 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()}")
|
|
```
|
|
|
|
### Hydrostatics Calculation
|
|
|
|
```python
|
|
from navaltoolbox import Hull, Vessel, HydrostaticsCalculator
|
|
|
|
# Create vessel
|
|
hull = Hull("ship.stl")
|
|
vessel = Vessel(hull)
|
|
|
|
# Calculate hydrostatics at a given draft
|
|
calc = HydrostaticsCalculator(vessel, water_density=1025.0)
|
|
|
|
# Option 1: At draft with VCG (computes stability)
|
|
state = calc.calculate_at_draft(draft=5.0, vcg=7.0)
|
|
|
|
print(f"Volume: {state.volume:.1f} m³")
|
|
print(f"Displacement: {state.displacement:.0f} kg")
|
|
print(f"COB: ({state.cob[0]:.2f}, {state.cob[1]:.2f}, {state.cob[2]:.2f})")
|
|
print(f"Waterplane Area: {state.waterplane_area:.1f} m²")
|
|
print(f"LCF: {state.lcf:.2f} m")
|
|
print(f"GMT (wet): {state.gmt:.3f} m")
|
|
print(f"GMT (dry): {state.gmt_dry:.3f} m")
|
|
|
|
# Option 2: Find draft for displacement
|
|
state_disp = calc.calculate_at_displacement(512500.0)
|
|
print(f"Draft for {state_disp.displacement:.0f}kg: {state_disp.draft:.3f} m")
|
|
```
|
|
|
|
### Stability Analysis (GZ Curve)
|
|
|
|
```python
|
|
from navaltoolbox import Hull, Vessel, StabilityCalculator
|
|
|
|
# Create vessel and calculator
|
|
hull = Hull("ship.stl")
|
|
vessel = Vessel(hull)
|
|
calc = StabilityCalculator(vessel, water_density=1025.0)
|
|
|
|
# Calculate GZ curve
|
|
displacement_mass = 8635000.0 # kg
|
|
cog = (71.67, 0.0, 7.555) # LCG, TCG, VCG in meters
|
|
heels = [0, 10, 20, 30, 40, 50, 60, 70, 80, 90]
|
|
|
|
curve = calc.calculate_gz_curve(displacement_mass, cog, heels)
|
|
|
|
# Display results
|
|
print("Heel (°) | GZ (m)")
|
|
print("-" * 25)
|
|
for heel, gz in zip(curve.heels(), curve.values()):
|
|
print(f"{heel:7.1f} | {gz:7.3f}")
|
|
|
|
# Get max GZ
|
|
gz_values = curve.values()
|
|
max_gz = max(gz_values)
|
|
max_idx = gz_values.index(max_gz)
|
|
max_heel = heels[max_idx]
|
|
print(f"\nMax GZ: {max_gz:.3f}m at {max_heel}°")
|
|
```
|
|
|
|
### Tank Management
|
|
|
|
```python
|
|
from navaltoolbox import Tank, Vessel, Hull
|
|
|
|
# Create a vessel
|
|
hull = Hull("ship.stl")
|
|
vessel = Vessel(hull)
|
|
|
|
# Add a box-shaped tank
|
|
tank = Tank.from_box(
|
|
name="Fuel Tank 1",
|
|
x_min=40.0, x_max=50.0,
|
|
y_min=-5.0, y_max=5.0,
|
|
z_min=0.0, z_max=3.0,
|
|
fluid_density=850.0 # diesel fuel
|
|
)
|
|
|
|
vessel.add_tank(tank)
|
|
|
|
# Set fill level
|
|
tank.fill_percent = 75.0
|
|
|
|
# Get tank properties
|
|
print(f"Tank: {tank.name}")
|
|
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"Center of gravity: {tank.center_of_gravity}")
|
|
print(f"Free surface moment (transverse): {tank.free_surface_moment_t:.2f} m⁴")
|
|
```
|
|
|
|
### Multi-hull Vessels
|
|
|
|
```python
|
|
from navaltoolbox import Hull, Vessel
|
|
|
|
# Load individual hulls
|
|
port_hull = Hull("port_hull.stl")
|
|
starboard_hull = Hull("starboard_hull.stl")
|
|
|
|
# Create catamaran
|
|
catamaran = Vessel(port_hull)
|
|
catamaran.add_hull(starboard_hull, offset=(0.0, 8.0, 0.0)) # 8m beam between hulls
|
|
|
|
# Calculate hydrostatics
|
|
calc = HydrostaticsCalculator(catamaran, water_density=1025.0)
|
|
state = calc.calculate_at_draft(1.5)
|
|
|
|
print(f"Catamaran displacement: {state.displacement:.0f} kg")
|
|
print(f"Waterplane area: {state.waterplane_area:.1f} m²")
|
|
```
|
|
|
|
### Downflooding Detection
|
|
|
|
```python
|
|
from navaltoolbox import Hull, Vessel, DownfloodingOpening, StabilityCalculator
|
|
|
|
# Create vessel
|
|
hull = Hull("ship.stl")
|
|
vessel = Vessel(hull)
|
|
|
|
# Add downflooding opening (e.g., air pipe, ventilator)
|
|
opening = DownfloodingOpening.from_point(
|
|
name="Vent pipe",
|
|
x=75.0, y=9.8, z=12.5,
|
|
opening_type="vent"
|
|
)
|
|
vessel.add_downflooding_opening(opening)
|
|
|
|
# Calculate GZ curve with downflooding detection
|
|
calc = StabilityCalculator(vessel, water_density=1025.0)
|
|
heels = list(range(0, 95, 5))
|
|
curve = calc.calculate_gz_curve(8635000.0, (71.67, 0.0, 7.555), heels)
|
|
|
|
# Check for downflooding
|
|
for point in curve.points():
|
|
if point.is_flooding:
|
|
print(f"⚠️ Downflooding at {point.heel}° - {', '.join(point.flooded_openings)}")
|
|
```
|
|
|
|
## Documentation
|
|
|
|
For more detailed documentation, examples, and API reference, visit:
|
|
- **GitHub Repository**: [NavalToolbox/navaltoolbox-lib](https://github.com/NavalToolbox/navaltoolbox-lib)
|
|
- **Issue Tracker**: [GitHub Issues](https://github.com/NavalToolbox/navaltoolbox-lib/issues)
|
|
|
|
## Performance
|
|
|
|
NavalToolbox is built with performance in mind:
|
|
|
|
- Written in **Rust** for maximum speed and memory safety
|
|
- Efficient mesh operations using `parry3d`
|
|
- Parallel processing where applicable
|
|
- Zero-copy data transfer between Python and Rust
|
|
|
|
Example benchmark (DTMB 5415 hull, 3436 triangles):
|
|
- Load STL: ~10ms
|
|
- Hydrostatics calculation: ~50ms
|
|
- GZ curve (13 points): ~650ms
|
|
|
|
## Use Cases
|
|
|
|
NavalToolbox is suitable for:
|
|
|
|
- 🎓 **Naval architecture education**: Teaching hydrostatics and stability
|
|
- 🔬 **Research**: Rapid prototyping of new methods and algorithms
|
|
- 🏭 **Engineering**: Production stability calculations and analysis
|
|
- 🤖 **Optimization**: Integration with optimization frameworks
|
|
- 📊 **Batch processing**: Analyzing multiple design variants
|
|
|
|
## Requirements and Compatibility
|
|
|
|
- **Python**: 3.9, 3.10, 3.11, 3.12, 3.13
|
|
- **Operating Systems**:
|
|
- macOS (Intel and Apple Silicon)
|
|
- Linux (x86_64, aarch64)
|
|
- Windows (x86_64)
|
|
- **File Formats**:
|
|
- Hull geometry: STL (binary and ASCII), VTK
|
|
- Silhouettes: DXF, VTK
|
|
|
|
## Contributing
|
|
|
|
Contributions are welcome! Please feel free to submit issues, feature requests, or pull requests on GitHub.
|
|
|
|
## License
|
|
|
|
This project is licensed under the **GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later)**.
|
|
|
|
This means:
|
|
- ✅ Free to use, modify, and distribute
|
|
- ✅ Can be used in commercial projects
|
|
- ⚠️ Source code must be made available under AGPL
|
|
- ⚠️ Network use is considered distribution (AGPL provision)
|
|
|
|
See the [LICENSE](https://github.com/NavalToolbox/navaltoolbox-lib/blob/main/LICENSE) file for details.
|
|
|
|
## Citation
|
|
|
|
If you use NavalToolbox in your research, please cite:
|
|
|
|
```bibtex
|
|
@software{navaltoolbox2026,
|
|
author = {Anceau, Antoine},
|
|
title = {NavalToolbox: High-performance naval architecture library},
|
|
year = {2026},
|
|
url = {https://github.com/NavalToolbox/navaltoolbox-lib}
|
|
}
|
|
```
|
|
|
|
## Author
|
|
|
|
**Antoine ANCEAU**
|
|
- GitHub: [@antoineanceau](https://github.com/antoineanceau)
|
|
- Website: [antoine.anceau.fr](https://antoine.anceau.fr)
|
|
|
|
## Support
|
|
|
|
- 📖 **Documentation**: [GitHub Pages](https://navaltoolbox.github.io/navaltoolbox-lib)
|
|
- 🐛 **Bug Reports**: [Open an issue](https://github.com/NavalToolbox/navaltoolbox-lib/issues)
|
|
- 💬 **Discussions**: [GitHub Discussions](https://github.com/NavalToolbox/navaltoolbox-lib/discussions)
|
|
- 📧 **Email**: For private inquiries
|
|
|
|
---
|
|
|
|
**Note**: This package uses a Rust backend for high performance. Pre-built wheels are provided for common platforms. If a wheel is not available for your platform, the package will attempt to build from source (requires Rust toolchain).
|