CargoOptix is an intelligent cargo placement system designed to optimize container loading on feeder ships while ensuring maritime safety compliance. The system combines constraint-based optimization with naval architecture physics to generate safe, efficient loading plans that maximize space utilization while maintaining ship stability.

Traditional maritime cargo operations face critical challenges:

❌ Manual planning takes 2-3 hours per ship

❌ Suboptimal space utilization (60-70%)

❌ Risk of stability violations and capsizing

❌ No real-time constraint validation

❌ Human error in hazmat separation and weight distribution

✅ 91% placement success rate with automated optimization

✅ 84% slot utilization - significantly higher than manual methods

✅ Real-time stability validation ensuring GM > safety threshold

✅ Constraint enforcement for hazmat, reefer, and weight limits

✅ Minutes instead of hours for complete loading plans

py3dbc Library - Our contribution to open-source maritime logistics:

Extends py3dbp with maritime domain expertise

First library combining 3D bin packing with ship stability physics

Discrete bay/row/tier slot structure matching real ship geometry

Constraint validation framework for maritime regulations

Container Manifest (CSV): - 632 containers (general, reefer, hazmat) - Varied weights (4-30 tonnes) - Mixed sizes (20ft, 40ft) Ship Specifications: - 7 bays × 14 rows × 7 tiers = 686 slots - Deadweight: 13,500 tonnes - GM minimum: 0.3m

✅ Placement Performance: - 576/632 containers placed (91.14%) - 762 TEU loaded - 83.97% slot utilization ✅ Stability Analysis: - GM: 1.273m (4.2× minimum requirement) - KG: 7.427m - Status: STABLE ✓ - Margin: 0.973m above threshold ✅ Constraints Satisfied: - All hazmat separated by 3+ positions - 41 reefers in powered slots - Weight limits enforced per tier

# Python 3.8 or higher required python --version # Required packages pip install pandas numpy py3dbp

git clone https://github.com/SarthSatpute/cargooptix.git cd cargooptix pip install -r requirements.txt

cargooptix/ ├── py3dbc/ # Maritime optimization library │ ├── maritime/ │ │ ├── container.py # Container classes with cargo types │ │ ├── ship.py # Ship structure and slot management │ │ ├── constraints.py # Maritime rule enforcement │ │ └── packer.py # Optimization algorithm │ └── physics/ │ └── stability.py # GM/KG calculations ├── data/ │ ├── generate_datasets.py # Synthetic data generation │ └── *.csv # Generated scenarios ├── load_scenario.py # Run optimization on CSV data ├── example_py3dbc.py # Usage examples └── README.md

from py3dbc.maritime.container import MaritimeContainer from py3dbc.maritime.ship import ContainerShip from py3dbc.maritime.packer import MaritimePacker # Initialize ship stability_params = { 'kg_lightship': 6.5, 'lightship_weight': 3500, 'kb': 4.2, 'bm': 4.5, 'gm_min': 0.3 } ship = ContainerShip( ship_name='FEEDER_01', dimensions=(130, 20, 18), bays=7, rows=14, tiers=7, stability_params=stability_params, max_weight=13500 ) # Create containers containers = [\ MaritimeContainer('GEN001', '20ft', 'general', 22.5, (6.06, 2.44, 2.59)),\ MaritimeContainer('REF001', '20ft', 'reefer', 18.0, (6.06, 2.44, 2.59)),\ MaritimeContainer('HAZ001', '20ft', 'hazmat', 14.5, (6.06, 2.44, 2.59))\ ] # Optimize packer = MaritimePacker(ship, gm_threshold=0.3, hazmat_separation=3) result = packer.pack(containers, strategy='heavy_first') print(f"Success: {result['success']}") print(f"Placement rate: {result['metrics']['placement_rate']}%") print(f"GM: {result['metrics']['gm']}m")

from load_scenario import optimize_scenario # Run optimization on scenario from generated data result = optimize_scenario(scenario_id=1)

python data/generate_datasets.py

Generates:

ship_specifications.csv - Ship parameters

container_manifests.csv - 20 scenarios with 600+ containers each

scenario_metadata.csv - Scenario requirements

┌─────────────────────────────────────────────────┐ │ Input: Container Manifest │ │ (CSV with dimensions, weights, cargo types) │ └────────────────┬────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────┐ │ MaritimePacker (Optimizer) │ │ ┌─────────────────────────────────────────┐ │ │ │ 1. Sort containers (heavy_first) │ │ │ │ 2. For each container: │ │ │ │ - Find available slots │ │ │ │ - Check constraints ──────────────┐ │ │ │ │ - Simulate stability │ │ │ │ │ - Score valid slots │ │ │ │ │ - Place in best slot │ │ │ │ └─────────────────────────────────────────┘ │ └────────────────┬────────────────────────────────┘ │ ┌────────────┴────────────┐ │ │ ▼ ▼ ┌──────────────┐ ┌──────────────────┐ │ Constraint │ │ Stability │ │ Checker │ │ Calculator │ ├──────────────┤ ├──────────────────┤ │ • Weight │ │ • KG = Σ(w×h)/Σw │ │ • Hazmat │ │ • GM = KB+BM-KG │ │ • Reefer │ │ • Check GM≥min │ └──────────────┘ └──────────────────┘ │ ▼ ┌─────────────────────────────────────────────────┐ │ Output: Optimized Loading Plan │ │ • Container-to-slot assignments │ │ • Stability metrics (GM, KG) │ │ • Utilization statistics │ │ • Constraint violations (if any) │ └─────────────────────────────────────────────────┘

Sort containers by strategy (weight/priority/hazmat)

For each container, evaluate all available slots

Filter slots that satisfy constraints (weight, reefer, hazmat)

Simulate stability for each valid slot

Score slots based on tier preference, stability margin, centerline proximity

Place container in highest-scoring valid slot

Update ship state and continue

KG = (lightship_weight × kg_lightship + Σ(container_weight × z_position)) / total_weight GM = KB + BM - KG Where: - KB: Center of buoyancy (4.2m) - BM: Metacentric radius (4.5m) - KG: Center of gravity (calculated)

Average placement rate: 91.2%

All scenarios maintained GM > 0.3m (100% stability success)

Reefer constraints: Primary cause of failed placements (powered slot shortage)

Hazmat separation: Successfully enforced in all cases

Failed placements occur due to:

Reefer power shortage - Only 14% of slots have power

Hazmat separation conflicts - 3-position minimum distance

High utilization - Limited valid slots at 80%+ capacity

This is realistic and matches commercial system performance.

Applied constraint satisfaction in real-world optimization

Integrated domain-specific physics (naval architecture)

Extended open-source library with specialized features

Developed end-to-end system from data generation to optimization

Demonstrated software engineering practices (OOP, modular design)

API Reference - Complete function documentation

Algorithm Details - Mathematical formulations

Constraint Specifications - Maritime rules

Examples - Usage tutorials and test cases

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Areas for enhancement:

Genetic algorithm implementation for comparison

Multi-port discharge sequence optimization

Crane scheduling integration

Real-time visualization (3D rendering)

Machine learning for slot prediction

This project is licensed under the MIT License - see the LICENSE file for details.

Built on py3dbp by jerry800416

Naval architecture formulas from standard maritime engineering texts

Inspired by real-world port operation challenges