py3dbc 1.0.0__tar.gz

py3dbc-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Sarth Satpute
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

py3dbc-1.0.0/PKG-INFO

@@ -0,0 +1,259 @@
+Metadata-Version: 2.4
+Name: py3dbc
+Version: 1.0.0
+Summary: 3D Bin Packing for Containers - Maritime optimization with ship stability physics
+Home-page: https://github.com/SarthSatpute/py3dbc
+Author: Sarth Satpute
+Author-email: your.email@example.com
+License: MIT
+Project-URL: Bug Tracker, https://github.com/SarthSatpute/py3dbc/issues
+Project-URL: Documentation, https://github.com/SarthSatpute/py3dbc#readme
+Project-URL: Source Code, https://github.com/SarthSatpute/py3dbc
+Keywords: 3d-bin-packing,container-optimization,maritime,ship-stability,logistics,cargo
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: py3dbp>=1.1.0
+Requires-Dist: pandas>=1.3.0
+Requires-Dist: numpy>=1.21.0
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: project-url
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+<div align="center">
+
+# 🚢 py3dbc
+
+### 3D Bin Packing for Containers
+
+*Maritime optimization library with ship stability physics*
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+[![Based on py3dbp](https://img.shields.io/badge/extends-py3dbp-orange)](https://github.com/jerry800416/3D-bin-packing)
+
+---
+
+</div>
+
+## 📖 What is py3dbc?
+
+**py3dbc** (3D Bin Packing for Containers) extends the popular [py3dbp](https://github.com/jerry800416/3D-bin-packing) library with **maritime-specific features** for container ship cargo optimization.
+
+While py3dbp handles general 3D packing, it doesn't account for **ship stability physics** or **maritime safety regulations**. py3dbc bridges this gap.
+
+---
+
+## 🎯 Key Features
+
+### ⚓ Ship Stability Validation
+- Real-time **metacentric height (GM)** calculations
+- Ensures ships won't capsize due to poor weight distribution
+- Validates safety after every container placement
+
+### 🛡️ Maritime Safety Constraints
+- **Hazmat Separation:** Keeps dangerous goods at safe distances
+- **Reefer Power:** Allocates refrigerated containers to powered slots
+- **Weight Limits:** Enforces tier capacity and stacking restrictions
+- **Regulatory Compliance:** Follows IMO and maritime standards
+
+### 📦 Container Types
+- General cargo (standard containers)
+- Reefer containers (refrigerated, need power)
+- Hazmat containers (dangerous goods, need separation)
+- Automatic TEU calculation (20ft = 1 TEU, 40ft = 2 TEU)
+
+### 🏗️ Realistic Ship Structure
+- Discrete **bay/row/tier** slot grid (matches real ship geometry)
+- 3D coordinates for each slot
+- Stack weight tracking per position
+
+---
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+pip install py3dbp pandas numpy
+git clone https://github.com/yourusername/py3dbc.git
+cd py3dbc
+pip install -e .
+```
+
+### Basic Usage
+
+```python
+from py3dbc.maritime.ship import ContainerShip
+from py3dbc.maritime.container import MaritimeContainer
+from py3dbc.maritime.packer import MaritimePacker
+
+# Create ship
+ship = ContainerShip(
+    ship_name='FEEDER_01',
+    bays=7, rows=14, tiers=7,
+    stability_params={'kg_lightship': 6.5, 'gm_min': 0.3, ...}
+)
+
+# Create containers
+containers = [
+    MaritimeContainer('GEN001', '20ft', 'general', 22.5, dimensions),
+    MaritimeContainer('REF001', '20ft', 'reefer', 18.0, dimensions),
+    MaritimeContainer('HAZ001', '20ft', 'hazmat', 14.5, dimensions)
+]
+
+# Optimize placement
+packer = MaritimePacker(ship)
+result = packer.pack(containers, strategy='heavy_first')
+
+# Check results
+print(f"Success Rate: {result['metrics']['placement_rate']}%")
+print(f"Ship Stable: {result['metrics']['is_stable']}")
+print(f"Final GM: {result['metrics']['gm']}m")
+```
+
+---
+
+## 🧮 How It Works
+
+### Stability Physics
+
+py3dbc calculates **metacentric height (GM)** using naval architecture principles:
+
+```
+GM = KB + BM - KG
+
+Where:
+  KB = Center of buoyancy (ship constant)
+  BM = Metacentric radius (ship geometry)
+  KG = Center of gravity (changes as cargo loads)
+
+If GM < minimum → Ship is unstable (placement rejected)
+```
+
+### Optimization Process
+
+1. **Sort containers** (heavy first, by priority, or hazmat first)
+2. **For each container:**
+   - Find available slots
+   - Check constraints (weight, power, separation, stability)
+   - Score valid slots (tier preference, centerline, stability margin)
+   - Place in best slot
+3. **Update ship state** (weight, GM, occupancy)
+4. **Repeat** until all containers placed or no valid slots remain
+
+---
+
+## 📊 Performance
+
+Tested on realistic scenarios:
+- **91% placement rate** (576 of 632 containers)
+- **84% slot utilization** (vs 60-70% manual planning)
+- **100% stability compliance** (GM always above minimum)
+- **Processes 600+ containers in under 2 minutes**
+
+---
+
+## 🔧 Use Cases
+
+- **Port Operations:** Automated cargo loading plans
+- **Maritime Logistics:** Pre-planning container placement
+- **Safety Validation:** Verify manual loading plans meet stability requirements
+- **Training/Education:** Demonstrate naval architecture principles
+- **Research:** Maritime optimization algorithms
+
+---
+
+## 📚 Documentation
+
+### Main Classes
+
+**MaritimeContainer**
+- Extends py3dbp's `Item` class
+- Adds cargo type, hazmat class, reefer flag, TEU value
+
+**ContainerShip**
+- Extends py3dbp's `Bin` class
+- Adds bay/row/tier grid structure, stability parameters
+
+**MaritimePacker**
+- Optimization engine with constraint validation
+- Multiple strategies: heavy_first, priority, hazmat_first
+
+**StabilityCalculator**
+- Naval architecture physics (GM/KG calculations)
+- Real-time stability validation
+
+**MaritimeConstraintChecker**
+- Validates weight limits, hazmat separation, reefer power
+- Ensures regulatory compliance
+
+---
+
+## 🎓 Academic Use
+
+py3dbc was developed as part of a B.Tech final year project at **K.K. Wagh Institute of Engineering, Nashik**.
+
+**Project:** CargoOptix - Automated Ship Load Balancing System  
+**Objective:** Combine constraint-based optimization with naval architecture physics  
+**Result:** Practical maritime optimization system with real-time safety validation
+
+---
+
+## 🤝 Contributing
+
+Contributions welcome! Areas for enhancement:
+- Genetic algorithm implementation
+- Multi-port discharge sequencing
+- Crane scheduling integration
+- Real-time weight sensor integration
+- Machine learning for slot prediction
+
+---
+
+## 📄 License
+
+This project is licensed under the MIT License - see [LICENSE](LICENSE) file.
+
+
+---
+
+
+---
+
+## 📞 Contact
+
+**Project Repository:** [github.com/SarthSatpute/py3dbc](https://github.com/SarthSatpute/py3dbc)  
+**Issues/Questions:** Open an issue on GitHub  
+**Related Project:** [CargoOptix]([https://github.com/SarthSatpute/CargoOptix]) - Full web application using py3dbc
+
+---
+
+<div align="center">
+
+**Built with ❤️ for safer, more efficient maritime operations**
+
+⭐ Star this repo if you find it useful!
+
+</div>

py3dbc-1.0.0/README.md

@@ -0,0 +1,216 @@
+<div align="center">
+
+# 🚢 py3dbc
+
+### 3D Bin Packing for Containers
+
+*Maritime optimization library with ship stability physics*
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+[![Based on py3dbp](https://img.shields.io/badge/extends-py3dbp-orange)](https://github.com/jerry800416/3D-bin-packing)
+
+---
+
+</div>
+
+## 📖 What is py3dbc?
+
+**py3dbc** (3D Bin Packing for Containers) extends the popular [py3dbp](https://github.com/jerry800416/3D-bin-packing) library with **maritime-specific features** for container ship cargo optimization.
+
+While py3dbp handles general 3D packing, it doesn't account for **ship stability physics** or **maritime safety regulations**. py3dbc bridges this gap.
+
+---
+
+## 🎯 Key Features
+
+### ⚓ Ship Stability Validation
+- Real-time **metacentric height (GM)** calculations
+- Ensures ships won't capsize due to poor weight distribution
+- Validates safety after every container placement
+
+### 🛡️ Maritime Safety Constraints
+- **Hazmat Separation:** Keeps dangerous goods at safe distances
+- **Reefer Power:** Allocates refrigerated containers to powered slots
+- **Weight Limits:** Enforces tier capacity and stacking restrictions
+- **Regulatory Compliance:** Follows IMO and maritime standards
+
+### 📦 Container Types
+- General cargo (standard containers)
+- Reefer containers (refrigerated, need power)
+- Hazmat containers (dangerous goods, need separation)
+- Automatic TEU calculation (20ft = 1 TEU, 40ft = 2 TEU)
+
+### 🏗️ Realistic Ship Structure
+- Discrete **bay/row/tier** slot grid (matches real ship geometry)
+- 3D coordinates for each slot
+- Stack weight tracking per position
+
+---
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+pip install py3dbp pandas numpy
+git clone https://github.com/yourusername/py3dbc.git
+cd py3dbc
+pip install -e .
+```
+
+### Basic Usage
+
+```python
+from py3dbc.maritime.ship import ContainerShip
+from py3dbc.maritime.container import MaritimeContainer
+from py3dbc.maritime.packer import MaritimePacker
+
+# Create ship
+ship = ContainerShip(
+    ship_name='FEEDER_01',
+    bays=7, rows=14, tiers=7,
+    stability_params={'kg_lightship': 6.5, 'gm_min': 0.3, ...}
+)
+
+# Create containers
+containers = [
+    MaritimeContainer('GEN001', '20ft', 'general', 22.5, dimensions),
+    MaritimeContainer('REF001', '20ft', 'reefer', 18.0, dimensions),
+    MaritimeContainer('HAZ001', '20ft', 'hazmat', 14.5, dimensions)
+]
+
+# Optimize placement
+packer = MaritimePacker(ship)
+result = packer.pack(containers, strategy='heavy_first')
+
+# Check results
+print(f"Success Rate: {result['metrics']['placement_rate']}%")
+print(f"Ship Stable: {result['metrics']['is_stable']}")
+print(f"Final GM: {result['metrics']['gm']}m")
+```
+
+---
+
+## 🧮 How It Works
+
+### Stability Physics
+
+py3dbc calculates **metacentric height (GM)** using naval architecture principles:
+
+```
+GM = KB + BM - KG
+
+Where:
+  KB = Center of buoyancy (ship constant)
+  BM = Metacentric radius (ship geometry)
+  KG = Center of gravity (changes as cargo loads)
+
+If GM < minimum → Ship is unstable (placement rejected)
+```
+
+### Optimization Process
+
+1. **Sort containers** (heavy first, by priority, or hazmat first)
+2. **For each container:**
+   - Find available slots
+   - Check constraints (weight, power, separation, stability)
+   - Score valid slots (tier preference, centerline, stability margin)
+   - Place in best slot
+3. **Update ship state** (weight, GM, occupancy)
+4. **Repeat** until all containers placed or no valid slots remain
+
+---
+
+## 📊 Performance
+
+Tested on realistic scenarios:
+- **91% placement rate** (576 of 632 containers)
+- **84% slot utilization** (vs 60-70% manual planning)
+- **100% stability compliance** (GM always above minimum)
+- **Processes 600+ containers in under 2 minutes**
+
+---
+
+## 🔧 Use Cases
+
+- **Port Operations:** Automated cargo loading plans
+- **Maritime Logistics:** Pre-planning container placement
+- **Safety Validation:** Verify manual loading plans meet stability requirements
+- **Training/Education:** Demonstrate naval architecture principles
+- **Research:** Maritime optimization algorithms
+
+---
+
+## 📚 Documentation
+
+### Main Classes
+
+**MaritimeContainer**
+- Extends py3dbp's `Item` class
+- Adds cargo type, hazmat class, reefer flag, TEU value
+
+**ContainerShip**
+- Extends py3dbp's `Bin` class
+- Adds bay/row/tier grid structure, stability parameters
+
+**MaritimePacker**
+- Optimization engine with constraint validation
+- Multiple strategies: heavy_first, priority, hazmat_first
+
+**StabilityCalculator**
+- Naval architecture physics (GM/KG calculations)
+- Real-time stability validation
+
+**MaritimeConstraintChecker**
+- Validates weight limits, hazmat separation, reefer power
+- Ensures regulatory compliance
+
+---
+
+## 🎓 Academic Use
+
+py3dbc was developed as part of a B.Tech final year project at **K.K. Wagh Institute of Engineering, Nashik**.
+
+**Project:** CargoOptix - Automated Ship Load Balancing System  
+**Objective:** Combine constraint-based optimization with naval architecture physics  
+**Result:** Practical maritime optimization system with real-time safety validation
+
+---
+
+## 🤝 Contributing
+
+Contributions welcome! Areas for enhancement:
+- Genetic algorithm implementation
+- Multi-port discharge sequencing
+- Crane scheduling integration
+- Real-time weight sensor integration
+- Machine learning for slot prediction
+
+---
+
+## 📄 License
+
+This project is licensed under the MIT License - see [LICENSE](LICENSE) file.
+
+
+---
+
+
+---
+
+## 📞 Contact
+
+**Project Repository:** [github.com/SarthSatpute/py3dbc](https://github.com/SarthSatpute/py3dbc)  
+**Issues/Questions:** Open an issue on GitHub  
+**Related Project:** [CargoOptix]([https://github.com/SarthSatpute/CargoOptix]) - Full web application using py3dbc
+
+---
+
+<div align="center">
+
+**Built with ❤️ for safer, more efficient maritime operations**
+
+⭐ Star this repo if you find it useful!
+
+</div>

py3dbc-1.0.0/py3dbc/__init__.py

@@ -0,0 +1,24 @@
+"""
+py3dbc - 3D Bin Packing for Containers
+Maritime container ship load optimization with stability physics
+"""
+
+__version__ = "1.0.0"
+__author__ = "Sarth Satpute"
+__license__ = "MIT"
+
+# Import main classes for easy access
+from py3dbc.maritime.container import MaritimeContainer
+from py3dbc.maritime.ship import ContainerShip, Slot
+from py3dbc.maritime.packer import MaritimePacker
+from py3dbc.maritime.constraints import MaritimeConstraintChecker
+from py3dbc.physics.stability import StabilityCalculator
+
+__all__ = [
+    "MaritimeContainer",
+    "ContainerShip",
+    "Slot",
+    "MaritimePacker",
+    "MaritimeConstraintChecker",
+    "StabilityCalculator",
+]

py3dbc-1.0.0/py3dbc/maritime/__init__.py

@@ -0,0 +1,16 @@
+"""
+Maritime extensions for container ship optimization
+"""
+
+from .container import MaritimeContainer
+from .ship import ContainerShip, Slot
+from .constraints import MaritimeConstraintChecker
+from .packer import MaritimePacker
+
+__all__ = [
+    'MaritimeContainer', 
+    'ContainerShip', 
+    'Slot',
+    'MaritimeConstraintChecker',
+    'MaritimePacker'
+]