239 lines
8.6 KiB
Markdown
239 lines
8.6 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 with contact surface detection
|
|
- 📊 **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
|
|
- 📎 **Appendages**: Add arbitrary geometry (STL/VTK) or primitive shapes for volume and buoyancy contributions
|
|
- 📏 **Deck Edges**: Define deck edge contours (livet) for freeboard calculation and deck immersion point detection
|
|
- ⚖️ **Loading Conditions**: Compose mass inventories and tank overrides to build operational profiles
|
|
- 💨 **Wind Heeling**: Silhouette-based wind calculations (DXF/VTK support)
|
|
- 📝 **Scriptable Verification**: Rhai scripting engine for custom stability criteria
|
|
- 🧊 **3D Visualization**: Interactive vessel and hydrostatic visualization with Plotly
|
|
- 📈 **Plotting**: Built-in 2D plotting utilities with Matplotlib integration
|
|
- ⚡ **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.from_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.from_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.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}°")
|
|
```
|
|
|
|
### Loading Conditions
|
|
|
|
```python
|
|
from navaltoolbox import Hull, Vessel, Tank, LoadingCondition, MassCategory
|
|
|
|
# Create vessel with a tank
|
|
vessel = Vessel(Hull("ship.stl"))
|
|
vessel.add_tank(Tank.from_box("FO_1", 20.0, 30.0, -5.0, 5.0, 0.0, 2.0, 1000.0))
|
|
|
|
# Define loading condition
|
|
lc = LoadingCondition("Arrival")
|
|
lc.add_mass_simple("Lightship", 5000000.0, (40.0, 0.0, 5.0), MassCategory.lightship())
|
|
lc.set_tank_fill_percent("FO_1", 50.0)
|
|
|
|
# Import/Export (JSON or CSV)
|
|
# lc.save_json("arrival.json")
|
|
# lc2 = LoadingCondition.load_csv("departure.csv")
|
|
|
|
# Use convenience methods directly to seamlessly merge the solid masses and tank configurations:
|
|
from navaltoolbox import StabilityCalculator, HydrostaticsCalculator
|
|
|
|
stab_calc = StabilityCalculator(vessel)
|
|
curve = stab_calc.gz_curve_from_loading(lc, heels=[0, 10, 20, 30])
|
|
print(f"Calculated GZ max: {max(curve.values()):.3f} m")
|
|
|
|
hydro_calc = HydrostaticsCalculator(vessel)
|
|
state = hydro_calc.from_loading(lc)
|
|
print(f"Equilibrium Draft: {state.draft:.3f} m")
|
|
```
|
|
|
|
## Documentation
|
|
|
|
For more detailed documentation, examples, and API reference, visit:
|
|
- **Documentation**: [GitHub Pages](https://navaltoolbox.github.io/navaltoolbox-lib/)
|
|
- **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.
|
|
|
|
## Disclaimer
|
|
|
|
NavalToolbox has been developed with care to ensure that all models and methods are correct, and that calculations reflect the most accurate results achievable with the implemented algorithms. However, **results must not be considered as a guarantee of performance**. The author cannot be held responsible for any inaccuracies in the calculations or for any consequences arising from the use of this software. Users are advised to independently verify critical calculations and to use this software as a tool to support, not replace, professional engineering judgment.
|
|
|
|
## 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).
|