py3dbc 1.0.0__py3-none-any.whl → 1.0.2__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- py3dbc-1.0.2.dist-info/METADATA +369 -0
- {py3dbc-1.0.0.dist-info → py3dbc-1.0.2.dist-info}/RECORD +5 -5
- {py3dbc-1.0.0.dist-info → py3dbc-1.0.2.dist-info}/WHEEL +1 -1
- py3dbc-1.0.0.dist-info/METADATA +0 -259
- {py3dbc-1.0.0.dist-info → py3dbc-1.0.2.dist-info}/licenses/LICENSE +0 -0
- {py3dbc-1.0.0.dist-info → py3dbc-1.0.2.dist-info}/top_level.txt +0 -0
|
@@ -0,0 +1,369 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: py3dbc
|
|
3
|
+
Version: 1.0.2
|
|
4
|
+
Summary: 3D Bin Packing for Containers - Maritime optimization with ship stability physics
|
|
5
|
+
Home-page: https://github.com/SarthSatpute/py3dbc
|
|
6
|
+
Author: Sarth Satpute
|
|
7
|
+
Author-email: sarthsatpute18@gmail.com
|
|
8
|
+
License: MIT
|
|
9
|
+
Project-URL: Bug Tracker, https://github.com/SarthSatpute/py3dbc/issues
|
|
10
|
+
Project-URL: Documentation, https://github.com/SarthSatpute/py3dbc#readme
|
|
11
|
+
Project-URL: Source Code, https://github.com/SarthSatpute/py3dbc
|
|
12
|
+
Keywords: 3d-bin-packing,container-optimization,maritime,ship-stability,logistics,cargo
|
|
13
|
+
Classifier: Development Status :: 4 - Beta
|
|
14
|
+
Classifier: Intended Audience :: Developers
|
|
15
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
16
|
+
Classifier: Topic :: Scientific/Engineering
|
|
17
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
18
|
+
Classifier: Programming Language :: Python :: 3
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.8
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
22
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
23
|
+
Classifier: Operating System :: OS Independent
|
|
24
|
+
Requires-Python: >=3.8
|
|
25
|
+
Description-Content-Type: text/markdown
|
|
26
|
+
License-File: LICENSE
|
|
27
|
+
Requires-Dist: py3dbp>=1.1.0
|
|
28
|
+
Requires-Dist: pandas>=1.3.0
|
|
29
|
+
Requires-Dist: numpy>=1.21.0
|
|
30
|
+
Dynamic: author
|
|
31
|
+
Dynamic: author-email
|
|
32
|
+
Dynamic: classifier
|
|
33
|
+
Dynamic: description
|
|
34
|
+
Dynamic: description-content-type
|
|
35
|
+
Dynamic: home-page
|
|
36
|
+
Dynamic: keywords
|
|
37
|
+
Dynamic: license
|
|
38
|
+
Dynamic: license-file
|
|
39
|
+
Dynamic: project-url
|
|
40
|
+
Dynamic: requires-dist
|
|
41
|
+
Dynamic: requires-python
|
|
42
|
+
Dynamic: summary
|
|
43
|
+
|
|
44
|
+
# py3dbc
|
|
45
|
+
|
|
46
|
+
**3D Bin Packing for Container Ships**
|
|
47
|
+
|
|
48
|
+
Maritime cargo optimization library with physics-based stability validation.
|
|
49
|
+
|
|
50
|
+
[](https://opensource.org/licenses/MIT)
|
|
51
|
+
[](https://www.python.org/downloads/)
|
|
52
|
+
[](https://pypi.org/project/py3dbc/)
|
|
53
|
+
[](https://pepy.tech/project/py3dbc)
|
|
54
|
+
|
|
55
|
+
---
|
|
56
|
+
|
|
57
|
+
## Overview
|
|
58
|
+
|
|
59
|
+
**py3dbc** (3D Bin Packing for Containers) extends the [py3dbp](https://github.com/jerry800416/3D-bin-packing) library with maritime-specific constraints and naval architecture physics for container ship cargo optimization.
|
|
60
|
+
|
|
61
|
+
While py3dbp handles general 3D bin packing, it doesn't account for ship stability physics or maritime safety regulations. py3dbc addresses this gap by integrating metacentric height (GM) calculations, hazmat separation rules, and regulatory compliance checks.
|
|
62
|
+
|
|
63
|
+
---
|
|
64
|
+
|
|
65
|
+
## Key Features
|
|
66
|
+
|
|
67
|
+
### Ship Stability Validation
|
|
68
|
+
- Real-time metacentric height (GM) calculation using naval architecture principles
|
|
69
|
+
- Dynamic center of gravity (KG) tracking during container placement
|
|
70
|
+
- Automatic rejection of placements that would compromise ship stability
|
|
71
|
+
- Compliance with IMO stability standards (GM ≥ 0.3m)
|
|
72
|
+
|
|
73
|
+
### Maritime Safety Constraints
|
|
74
|
+
- **Hazmat Separation:** Enforces minimum Manhattan distance between dangerous goods
|
|
75
|
+
- **Reefer Power Allocation:** Assigns refrigerated containers only to powered slots
|
|
76
|
+
- **Weight Distribution:** Validates tier capacity and stack limits
|
|
77
|
+
- **Regulatory Compliance:** Ensures adherence to maritime safety standards
|
|
78
|
+
|
|
79
|
+
### Container Classification
|
|
80
|
+
- General cargo (standard dry containers)
|
|
81
|
+
- Reefer containers (temperature-controlled, require power)
|
|
82
|
+
- Hazmat containers (dangerous goods with separation requirements)
|
|
83
|
+
- Automatic TEU calculation (20ft = 1 TEU, 40ft = 2 TEU)
|
|
84
|
+
|
|
85
|
+
### Realistic Ship Modeling
|
|
86
|
+
- Discrete bay-row-tier slot grid matching actual ship geometry
|
|
87
|
+
- 3D spatial coordinates for visualization
|
|
88
|
+
- Stack weight tracking per position
|
|
89
|
+
- Support for variable ship configurations
|
|
90
|
+
|
|
91
|
+
---
|
|
92
|
+
|
|
93
|
+
## Installation
|
|
94
|
+
|
|
95
|
+
```bash
|
|
96
|
+
pip install py3dbc
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
**Requirements:** Python 3.8+
|
|
100
|
+
|
|
101
|
+
---
|
|
102
|
+
|
|
103
|
+
## Quick Start
|
|
104
|
+
|
|
105
|
+
```python
|
|
106
|
+
from py3dbc.maritime.ship import ContainerShip
|
|
107
|
+
from py3dbc.maritime.container import MaritimeContainer
|
|
108
|
+
from py3dbc.maritime.packer import MaritimePacker
|
|
109
|
+
|
|
110
|
+
# Initialize ship with stability parameters
|
|
111
|
+
ship = ContainerShip(
|
|
112
|
+
ship_name='FEEDER_01',
|
|
113
|
+
dimensions=(100, 20, 15),
|
|
114
|
+
bays=7,
|
|
115
|
+
rows=14,
|
|
116
|
+
tiers=7,
|
|
117
|
+
stability_params={
|
|
118
|
+
'kg_lightship': 6.5,
|
|
119
|
+
'lightship_weight': 3500,
|
|
120
|
+
'kb': 4.2,
|
|
121
|
+
'bm': 4.5,
|
|
122
|
+
'gm_min': 0.3
|
|
123
|
+
},
|
|
124
|
+
max_weight=8000
|
|
125
|
+
)
|
|
126
|
+
|
|
127
|
+
# Define containers
|
|
128
|
+
containers = [
|
|
129
|
+
MaritimeContainer(
|
|
130
|
+
container_id='GEN001',
|
|
131
|
+
teu_size='20ft',
|
|
132
|
+
cargo_type='general',
|
|
133
|
+
total_weight=22.5,
|
|
134
|
+
dimensions=(6.1, 2.4, 2.6)
|
|
135
|
+
),
|
|
136
|
+
MaritimeContainer(
|
|
137
|
+
container_id='REF001',
|
|
138
|
+
teu_size='20ft',
|
|
139
|
+
cargo_type='reefer',
|
|
140
|
+
total_weight=18.0,
|
|
141
|
+
dimensions=(6.1, 2.4, 2.6)
|
|
142
|
+
),
|
|
143
|
+
MaritimeContainer(
|
|
144
|
+
container_id='HAZ001',
|
|
145
|
+
teu_size='20ft',
|
|
146
|
+
cargo_type='hazmat',
|
|
147
|
+
total_weight=14.5,
|
|
148
|
+
dimensions=(6.1, 2.4, 2.6),
|
|
149
|
+
hazmat_class='Class_3'
|
|
150
|
+
)
|
|
151
|
+
]
|
|
152
|
+
|
|
153
|
+
# Run optimization
|
|
154
|
+
packer = MaritimePacker(ship, gm_threshold=0.3, hazmat_separation=3)
|
|
155
|
+
result = packer.pack(containers, strategy='heavy_first')
|
|
156
|
+
|
|
157
|
+
# Analyze results
|
|
158
|
+
print(f"Placement Success Rate: {result['metrics']['placement_rate']:.1f}%")
|
|
159
|
+
print(f"Ship Stability: {'STABLE' if result['metrics']['is_stable'] else 'UNSTABLE'}")
|
|
160
|
+
print(f"Final GM: {result['metrics']['gm']:.2f}m")
|
|
161
|
+
print(f"Slot Utilization: {result['metrics']['slot_utilization']:.1f}%")
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
---
|
|
165
|
+
|
|
166
|
+
## How It Works
|
|
167
|
+
|
|
168
|
+
### Stability Physics
|
|
169
|
+
|
|
170
|
+
py3dbc calculates metacentric height using fundamental naval architecture equations:
|
|
171
|
+
|
|
172
|
+
```
|
|
173
|
+
GM = KB + BM - KG
|
|
174
|
+
|
|
175
|
+
Where:
|
|
176
|
+
KB = Vertical center of buoyancy (ship constant)
|
|
177
|
+
BM = Metacentric radius (function of ship geometry)
|
|
178
|
+
KG = Vertical center of gravity (updated per placement)
|
|
179
|
+
|
|
180
|
+
Stability Criterion: GM ≥ GM_min (typically 0.3m for container ships)
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
The center of gravity is recalculated after each container placement using the moment-summation method, ensuring real-time stability validation throughout the packing process.
|
|
184
|
+
|
|
185
|
+
### Optimization Algorithm
|
|
186
|
+
|
|
187
|
+
The packing algorithm follows a greedy heuristic approach with constraint validation:
|
|
188
|
+
|
|
189
|
+
1. **Sort containers** by selected strategy (heavy_first, priority, or hazmat_first)
|
|
190
|
+
2. **For each container:**
|
|
191
|
+
- Identify all available slots matching size requirements
|
|
192
|
+
- Filter slots by hard constraints (weight limits, power availability, hazmat separation)
|
|
193
|
+
- Validate stability impact of each candidate placement
|
|
194
|
+
- Score remaining slots using weighted heuristics (tier preference, centerline proximity, stability margin)
|
|
195
|
+
- Place container in highest-scoring valid slot
|
|
196
|
+
3. **Update ship state** (weight distribution, GM, slot occupancy)
|
|
197
|
+
4. **Continue** until all containers placed or no valid slots remain
|
|
198
|
+
|
|
199
|
+
### Constraint Validation
|
|
200
|
+
|
|
201
|
+
**Weight Constraints:**
|
|
202
|
+
```python
|
|
203
|
+
Container weight ≤ Tier capacity
|
|
204
|
+
Stack weight ≤ Maximum stack limit (decreases with height)
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
**Hazmat Separation:**
|
|
208
|
+
```python
|
|
209
|
+
Manhattan distance = |bay₁ - bay₂| + |row₁ - row₂| + |tier₁ - tier₂|
|
|
210
|
+
Distance ≥ Minimum separation (default: 3 slots)
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
**Reefer Power:**
|
|
214
|
+
```python
|
|
215
|
+
Reefer containers → Only slots with power_available = True
|
|
216
|
+
General/Hazmat → Any available slot
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
---
|
|
220
|
+
|
|
221
|
+
## Performance
|
|
222
|
+
|
|
223
|
+
Validated on synthetic maritime scenarios:
|
|
224
|
+
|
|
225
|
+
| Metric | Result |
|
|
226
|
+
|--------|--------|
|
|
227
|
+
| Placement Success Rate | 91.1% |
|
|
228
|
+
| Slot Utilization | 83.9% |
|
|
229
|
+
| Stability Compliance | 100% |
|
|
230
|
+
| Processing Speed | <2s for 600+ containers |
|
|
231
|
+
|
|
232
|
+
Comparison with manual planning: 20-30% improvement in utilization while maintaining 100% stability compliance.
|
|
233
|
+
|
|
234
|
+
---
|
|
235
|
+
|
|
236
|
+
## Use Cases
|
|
237
|
+
|
|
238
|
+
- **Port Terminal Operations:** Automated generation of container loading plans
|
|
239
|
+
- **Maritime Logistics:** Pre-voyage cargo optimization and stowage planning
|
|
240
|
+
- **Safety Validation:** Verification of manual load plans against stability requirements
|
|
241
|
+
- **Training and Education:** Demonstration of naval architecture principles and constraint optimization
|
|
242
|
+
- **Research:** Algorithm development for maritime optimization problems
|
|
243
|
+
|
|
244
|
+
---
|
|
245
|
+
|
|
246
|
+
## API Reference
|
|
247
|
+
|
|
248
|
+
### Core Classes
|
|
249
|
+
|
|
250
|
+
#### `MaritimeContainer`
|
|
251
|
+
|
|
252
|
+
Extends py3dbp's `Item` class with maritime-specific attributes.
|
|
253
|
+
|
|
254
|
+
**Parameters:**
|
|
255
|
+
- `container_id` (str): Unique container identifier
|
|
256
|
+
- `teu_size` (str): '20ft' or '40ft'
|
|
257
|
+
- `cargo_type` (str): 'general', 'reefer', or 'hazmat'
|
|
258
|
+
- `total_weight` (float): Container weight in tonnes
|
|
259
|
+
- `dimensions` (tuple): (length, width, height) in meters
|
|
260
|
+
- `hazmat_class` (str, optional): Hazmat classification if applicable
|
|
261
|
+
- `loading_priority` (int, optional): Priority level for placement
|
|
262
|
+
|
|
263
|
+
#### `ContainerShip`
|
|
264
|
+
|
|
265
|
+
Extends py3dbp's `Bin` class with ship-specific structure and stability parameters.
|
|
266
|
+
|
|
267
|
+
**Parameters:**
|
|
268
|
+
- `ship_name` (str): Ship identifier
|
|
269
|
+
- `dimensions` (tuple): (length, beam, depth) in meters
|
|
270
|
+
- `bays` (int): Number of longitudinal sections
|
|
271
|
+
- `rows` (int): Number of transverse positions
|
|
272
|
+
- `tiers` (int): Number of vertical levels
|
|
273
|
+
- `stability_params` (dict): Naval architecture constants
|
|
274
|
+
- `max_weight` (float): Deadweight capacity in tonnes
|
|
275
|
+
|
|
276
|
+
#### `MaritimePacker`
|
|
277
|
+
|
|
278
|
+
Main optimization engine with integrated constraint validation.
|
|
279
|
+
|
|
280
|
+
**Parameters:**
|
|
281
|
+
- `ship` (ContainerShip): Ship instance to pack
|
|
282
|
+
- `gm_threshold` (float): Minimum acceptable GM in meters
|
|
283
|
+
- `hazmat_separation` (int): Minimum slot distance between hazmat containers
|
|
284
|
+
|
|
285
|
+
**Methods:**
|
|
286
|
+
- `pack(containers, strategy)`: Execute packing algorithm
|
|
287
|
+
- Returns: Dictionary with placement results and metrics
|
|
288
|
+
|
|
289
|
+
**Available Strategies:**
|
|
290
|
+
- `'heavy_first'`: Sort by weight (descending)
|
|
291
|
+
- `'priority'`: Sort by loading priority
|
|
292
|
+
- `'hazmat_first'`: Place hazmat containers first
|
|
293
|
+
|
|
294
|
+
---
|
|
295
|
+
|
|
296
|
+
## Advanced Usage
|
|
297
|
+
|
|
298
|
+
### Custom Scoring Function
|
|
299
|
+
|
|
300
|
+
```python
|
|
301
|
+
# Modify slot scoring weights
|
|
302
|
+
packer = MaritimePacker(ship, gm_threshold=0.3)
|
|
303
|
+
packer.tier_weight = 0.4 # Prefer lower tiers
|
|
304
|
+
packer.stability_weight = 0.3 # Balance stability
|
|
305
|
+
packer.centerline_weight = 0.2 # Prefer centerline
|
|
306
|
+
packer.bay_weight = 0.1 # Forward placement preference
|
|
307
|
+
```
|
|
308
|
+
|
|
309
|
+
### Multi-Strategy Optimization
|
|
310
|
+
|
|
311
|
+
```python
|
|
312
|
+
strategies = ['heavy_first', 'priority', 'hazmat_first']
|
|
313
|
+
results = []
|
|
314
|
+
|
|
315
|
+
for strategy in strategies:
|
|
316
|
+
result = packer.pack(containers.copy(), strategy=strategy)
|
|
317
|
+
results.append(result)
|
|
318
|
+
|
|
319
|
+
# Select best result by placement rate
|
|
320
|
+
best_result = max(results, key=lambda r: r['metrics']['placement_rate'])
|
|
321
|
+
```
|
|
322
|
+
|
|
323
|
+
|
|
324
|
+
|
|
325
|
+
|
|
326
|
+
## License
|
|
327
|
+
|
|
328
|
+
This project is licensed under the MIT License. See [LICENSE](LICENSE) file for details.
|
|
329
|
+
|
|
330
|
+
---
|
|
331
|
+
|
|
332
|
+
## Citation
|
|
333
|
+
|
|
334
|
+
If you use py3dbc in academic research, please cite:
|
|
335
|
+
|
|
336
|
+
```bibtex
|
|
337
|
+
@software{py3dbc2025,
|
|
338
|
+
author = {Satpute Sarth, Pardeshi Pranav},
|
|
339
|
+
title = {py3dbc: 3D Bin Packing for Container Ships},
|
|
340
|
+
year = {2025},
|
|
341
|
+
publisher = {PyPI},
|
|
342
|
+
url = {https://pypi.org/project/py3dbc/}
|
|
343
|
+
}
|
|
344
|
+
```
|
|
345
|
+
|
|
346
|
+
---
|
|
347
|
+
|
|
348
|
+
## Support
|
|
349
|
+
|
|
350
|
+
- **Documentation:** [GitHub Repository](https://github.com/SarthSatpute/py3dbc)
|
|
351
|
+
- **Issues:** [GitHub Issues](https://github.com/SarthSatpute/py3dbc/issues)
|
|
352
|
+
- **Discussions:** [GitHub Discussions](https://github.com/SarthSatpute/py3dbc/discussions)
|
|
353
|
+
|
|
354
|
+
---
|
|
355
|
+
|
|
356
|
+
## Related Projects
|
|
357
|
+
|
|
358
|
+
- **CargoOptix:** Full-stack web application using py3dbc for interactive cargo optimization
|
|
359
|
+
- **py3dbp:** Base library for general 3D bin packing (credit to original authors)
|
|
360
|
+
|
|
361
|
+
---
|
|
362
|
+
|
|
363
|
+
## Acknowledgments
|
|
364
|
+
|
|
365
|
+
Built upon the [py3dbp](https://github.com/jerry800416/3D-bin-packing) library by jerry800416.
|
|
366
|
+
|
|
367
|
+
---
|
|
368
|
+
|
|
369
|
+
**If you find this library useful, please consider starring the repository.**
|
|
@@ -6,8 +6,8 @@ py3dbc/maritime/packer.py,sha256=Yt5Z2OoR-8RtPRoKrp-AMxDnly2SH75tuQ1-HF-UllE,861
|
|
|
6
6
|
py3dbc/maritime/ship.py,sha256=-p87e0x4NZDuXtkiXWmY7tMr_TTddKESjkmDThkiJu8,8479
|
|
7
7
|
py3dbc/physics/__init__.py,sha256=BiE18jtqNg4qDvsY1adKjrfBjSh1dIyuNCspvyd_P_o,132
|
|
8
8
|
py3dbc/physics/stability.py,sha256=-IFGBK7CVnbyh2qh5Qy-UPJwLVrGJmiN2mPPYdABjSc,3381
|
|
9
|
-
py3dbc-1.0.
|
|
10
|
-
py3dbc-1.0.
|
|
11
|
-
py3dbc-1.0.
|
|
12
|
-
py3dbc-1.0.
|
|
13
|
-
py3dbc-1.0.
|
|
9
|
+
py3dbc-1.0.2.dist-info/licenses/LICENSE,sha256=NX6kEjAfNQ0I-dEWnosDKy9zqBJHxmiABp-8s3558VE,1091
|
|
10
|
+
py3dbc-1.0.2.dist-info/METADATA,sha256=kpjjGqIp-1BNeRIyeOjlwMdjKSJty_g_EyrgH_vInH8,11732
|
|
11
|
+
py3dbc-1.0.2.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
|
|
12
|
+
py3dbc-1.0.2.dist-info/top_level.txt,sha256=KXLRFnnWt06PKi1jZyo0Anb4SFYN2fsoY41MYUXQBxc,7
|
|
13
|
+
py3dbc-1.0.2.dist-info/RECORD,,
|
py3dbc-1.0.0.dist-info/METADATA
DELETED
|
@@ -1,259 +0,0 @@
|
|
|
1
|
-
Metadata-Version: 2.4
|
|
2
|
-
Name: py3dbc
|
|
3
|
-
Version: 1.0.0
|
|
4
|
-
Summary: 3D Bin Packing for Containers - Maritime optimization with ship stability physics
|
|
5
|
-
Home-page: https://github.com/SarthSatpute/py3dbc
|
|
6
|
-
Author: Sarth Satpute
|
|
7
|
-
Author-email: your.email@example.com
|
|
8
|
-
License: MIT
|
|
9
|
-
Project-URL: Bug Tracker, https://github.com/SarthSatpute/py3dbc/issues
|
|
10
|
-
Project-URL: Documentation, https://github.com/SarthSatpute/py3dbc#readme
|
|
11
|
-
Project-URL: Source Code, https://github.com/SarthSatpute/py3dbc
|
|
12
|
-
Keywords: 3d-bin-packing,container-optimization,maritime,ship-stability,logistics,cargo
|
|
13
|
-
Classifier: Development Status :: 4 - Beta
|
|
14
|
-
Classifier: Intended Audience :: Developers
|
|
15
|
-
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
16
|
-
Classifier: Topic :: Scientific/Engineering
|
|
17
|
-
Classifier: License :: OSI Approved :: MIT License
|
|
18
|
-
Classifier: Programming Language :: Python :: 3
|
|
19
|
-
Classifier: Programming Language :: Python :: 3.8
|
|
20
|
-
Classifier: Programming Language :: Python :: 3.9
|
|
21
|
-
Classifier: Programming Language :: Python :: 3.10
|
|
22
|
-
Classifier: Programming Language :: Python :: 3.11
|
|
23
|
-
Classifier: Operating System :: OS Independent
|
|
24
|
-
Requires-Python: >=3.8
|
|
25
|
-
Description-Content-Type: text/markdown
|
|
26
|
-
License-File: LICENSE
|
|
27
|
-
Requires-Dist: py3dbp>=1.1.0
|
|
28
|
-
Requires-Dist: pandas>=1.3.0
|
|
29
|
-
Requires-Dist: numpy>=1.21.0
|
|
30
|
-
Dynamic: author
|
|
31
|
-
Dynamic: author-email
|
|
32
|
-
Dynamic: classifier
|
|
33
|
-
Dynamic: description
|
|
34
|
-
Dynamic: description-content-type
|
|
35
|
-
Dynamic: home-page
|
|
36
|
-
Dynamic: keywords
|
|
37
|
-
Dynamic: license
|
|
38
|
-
Dynamic: license-file
|
|
39
|
-
Dynamic: project-url
|
|
40
|
-
Dynamic: requires-dist
|
|
41
|
-
Dynamic: requires-python
|
|
42
|
-
Dynamic: summary
|
|
43
|
-
|
|
44
|
-
<div align="center">
|
|
45
|
-
|
|
46
|
-
# 🚢 py3dbc
|
|
47
|
-
|
|
48
|
-
### 3D Bin Packing for Containers
|
|
49
|
-
|
|
50
|
-
*Maritime optimization library with ship stability physics*
|
|
51
|
-
|
|
52
|
-
[](https://opensource.org/licenses/MIT)
|
|
53
|
-
[](https://www.python.org/downloads/)
|
|
54
|
-
[](https://github.com/jerry800416/3D-bin-packing)
|
|
55
|
-
|
|
56
|
-
---
|
|
57
|
-
|
|
58
|
-
</div>
|
|
59
|
-
|
|
60
|
-
## 📖 What is py3dbc?
|
|
61
|
-
|
|
62
|
-
**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.
|
|
63
|
-
|
|
64
|
-
While py3dbp handles general 3D packing, it doesn't account for **ship stability physics** or **maritime safety regulations**. py3dbc bridges this gap.
|
|
65
|
-
|
|
66
|
-
---
|
|
67
|
-
|
|
68
|
-
## 🎯 Key Features
|
|
69
|
-
|
|
70
|
-
### ⚓ Ship Stability Validation
|
|
71
|
-
- Real-time **metacentric height (GM)** calculations
|
|
72
|
-
- Ensures ships won't capsize due to poor weight distribution
|
|
73
|
-
- Validates safety after every container placement
|
|
74
|
-
|
|
75
|
-
### 🛡️ Maritime Safety Constraints
|
|
76
|
-
- **Hazmat Separation:** Keeps dangerous goods at safe distances
|
|
77
|
-
- **Reefer Power:** Allocates refrigerated containers to powered slots
|
|
78
|
-
- **Weight Limits:** Enforces tier capacity and stacking restrictions
|
|
79
|
-
- **Regulatory Compliance:** Follows IMO and maritime standards
|
|
80
|
-
|
|
81
|
-
### 📦 Container Types
|
|
82
|
-
- General cargo (standard containers)
|
|
83
|
-
- Reefer containers (refrigerated, need power)
|
|
84
|
-
- Hazmat containers (dangerous goods, need separation)
|
|
85
|
-
- Automatic TEU calculation (20ft = 1 TEU, 40ft = 2 TEU)
|
|
86
|
-
|
|
87
|
-
### 🏗️ Realistic Ship Structure
|
|
88
|
-
- Discrete **bay/row/tier** slot grid (matches real ship geometry)
|
|
89
|
-
- 3D coordinates for each slot
|
|
90
|
-
- Stack weight tracking per position
|
|
91
|
-
|
|
92
|
-
---
|
|
93
|
-
|
|
94
|
-
## 🚀 Quick Start
|
|
95
|
-
|
|
96
|
-
### Installation
|
|
97
|
-
|
|
98
|
-
```bash
|
|
99
|
-
pip install py3dbp pandas numpy
|
|
100
|
-
git clone https://github.com/yourusername/py3dbc.git
|
|
101
|
-
cd py3dbc
|
|
102
|
-
pip install -e .
|
|
103
|
-
```
|
|
104
|
-
|
|
105
|
-
### Basic Usage
|
|
106
|
-
|
|
107
|
-
```python
|
|
108
|
-
from py3dbc.maritime.ship import ContainerShip
|
|
109
|
-
from py3dbc.maritime.container import MaritimeContainer
|
|
110
|
-
from py3dbc.maritime.packer import MaritimePacker
|
|
111
|
-
|
|
112
|
-
# Create ship
|
|
113
|
-
ship = ContainerShip(
|
|
114
|
-
ship_name='FEEDER_01',
|
|
115
|
-
bays=7, rows=14, tiers=7,
|
|
116
|
-
stability_params={'kg_lightship': 6.5, 'gm_min': 0.3, ...}
|
|
117
|
-
)
|
|
118
|
-
|
|
119
|
-
# Create containers
|
|
120
|
-
containers = [
|
|
121
|
-
MaritimeContainer('GEN001', '20ft', 'general', 22.5, dimensions),
|
|
122
|
-
MaritimeContainer('REF001', '20ft', 'reefer', 18.0, dimensions),
|
|
123
|
-
MaritimeContainer('HAZ001', '20ft', 'hazmat', 14.5, dimensions)
|
|
124
|
-
]
|
|
125
|
-
|
|
126
|
-
# Optimize placement
|
|
127
|
-
packer = MaritimePacker(ship)
|
|
128
|
-
result = packer.pack(containers, strategy='heavy_first')
|
|
129
|
-
|
|
130
|
-
# Check results
|
|
131
|
-
print(f"Success Rate: {result['metrics']['placement_rate']}%")
|
|
132
|
-
print(f"Ship Stable: {result['metrics']['is_stable']}")
|
|
133
|
-
print(f"Final GM: {result['metrics']['gm']}m")
|
|
134
|
-
```
|
|
135
|
-
|
|
136
|
-
---
|
|
137
|
-
|
|
138
|
-
## 🧮 How It Works
|
|
139
|
-
|
|
140
|
-
### Stability Physics
|
|
141
|
-
|
|
142
|
-
py3dbc calculates **metacentric height (GM)** using naval architecture principles:
|
|
143
|
-
|
|
144
|
-
```
|
|
145
|
-
GM = KB + BM - KG
|
|
146
|
-
|
|
147
|
-
Where:
|
|
148
|
-
KB = Center of buoyancy (ship constant)
|
|
149
|
-
BM = Metacentric radius (ship geometry)
|
|
150
|
-
KG = Center of gravity (changes as cargo loads)
|
|
151
|
-
|
|
152
|
-
If GM < minimum → Ship is unstable (placement rejected)
|
|
153
|
-
```
|
|
154
|
-
|
|
155
|
-
### Optimization Process
|
|
156
|
-
|
|
157
|
-
1. **Sort containers** (heavy first, by priority, or hazmat first)
|
|
158
|
-
2. **For each container:**
|
|
159
|
-
- Find available slots
|
|
160
|
-
- Check constraints (weight, power, separation, stability)
|
|
161
|
-
- Score valid slots (tier preference, centerline, stability margin)
|
|
162
|
-
- Place in best slot
|
|
163
|
-
3. **Update ship state** (weight, GM, occupancy)
|
|
164
|
-
4. **Repeat** until all containers placed or no valid slots remain
|
|
165
|
-
|
|
166
|
-
---
|
|
167
|
-
|
|
168
|
-
## 📊 Performance
|
|
169
|
-
|
|
170
|
-
Tested on realistic scenarios:
|
|
171
|
-
- **91% placement rate** (576 of 632 containers)
|
|
172
|
-
- **84% slot utilization** (vs 60-70% manual planning)
|
|
173
|
-
- **100% stability compliance** (GM always above minimum)
|
|
174
|
-
- **Processes 600+ containers in under 2 minutes**
|
|
175
|
-
|
|
176
|
-
---
|
|
177
|
-
|
|
178
|
-
## 🔧 Use Cases
|
|
179
|
-
|
|
180
|
-
- **Port Operations:** Automated cargo loading plans
|
|
181
|
-
- **Maritime Logistics:** Pre-planning container placement
|
|
182
|
-
- **Safety Validation:** Verify manual loading plans meet stability requirements
|
|
183
|
-
- **Training/Education:** Demonstrate naval architecture principles
|
|
184
|
-
- **Research:** Maritime optimization algorithms
|
|
185
|
-
|
|
186
|
-
---
|
|
187
|
-
|
|
188
|
-
## 📚 Documentation
|
|
189
|
-
|
|
190
|
-
### Main Classes
|
|
191
|
-
|
|
192
|
-
**MaritimeContainer**
|
|
193
|
-
- Extends py3dbp's `Item` class
|
|
194
|
-
- Adds cargo type, hazmat class, reefer flag, TEU value
|
|
195
|
-
|
|
196
|
-
**ContainerShip**
|
|
197
|
-
- Extends py3dbp's `Bin` class
|
|
198
|
-
- Adds bay/row/tier grid structure, stability parameters
|
|
199
|
-
|
|
200
|
-
**MaritimePacker**
|
|
201
|
-
- Optimization engine with constraint validation
|
|
202
|
-
- Multiple strategies: heavy_first, priority, hazmat_first
|
|
203
|
-
|
|
204
|
-
**StabilityCalculator**
|
|
205
|
-
- Naval architecture physics (GM/KG calculations)
|
|
206
|
-
- Real-time stability validation
|
|
207
|
-
|
|
208
|
-
**MaritimeConstraintChecker**
|
|
209
|
-
- Validates weight limits, hazmat separation, reefer power
|
|
210
|
-
- Ensures regulatory compliance
|
|
211
|
-
|
|
212
|
-
---
|
|
213
|
-
|
|
214
|
-
## 🎓 Academic Use
|
|
215
|
-
|
|
216
|
-
py3dbc was developed as part of a B.Tech final year project at **K.K. Wagh Institute of Engineering, Nashik**.
|
|
217
|
-
|
|
218
|
-
**Project:** CargoOptix - Automated Ship Load Balancing System
|
|
219
|
-
**Objective:** Combine constraint-based optimization with naval architecture physics
|
|
220
|
-
**Result:** Practical maritime optimization system with real-time safety validation
|
|
221
|
-
|
|
222
|
-
---
|
|
223
|
-
|
|
224
|
-
## 🤝 Contributing
|
|
225
|
-
|
|
226
|
-
Contributions welcome! Areas for enhancement:
|
|
227
|
-
- Genetic algorithm implementation
|
|
228
|
-
- Multi-port discharge sequencing
|
|
229
|
-
- Crane scheduling integration
|
|
230
|
-
- Real-time weight sensor integration
|
|
231
|
-
- Machine learning for slot prediction
|
|
232
|
-
|
|
233
|
-
---
|
|
234
|
-
|
|
235
|
-
## 📄 License
|
|
236
|
-
|
|
237
|
-
This project is licensed under the MIT License - see [LICENSE](LICENSE) file.
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
---
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
---
|
|
244
|
-
|
|
245
|
-
## 📞 Contact
|
|
246
|
-
|
|
247
|
-
**Project Repository:** [github.com/SarthSatpute/py3dbc](https://github.com/SarthSatpute/py3dbc)
|
|
248
|
-
**Issues/Questions:** Open an issue on GitHub
|
|
249
|
-
**Related Project:** [CargoOptix]([https://github.com/SarthSatpute/CargoOptix]) - Full web application using py3dbc
|
|
250
|
-
|
|
251
|
-
---
|
|
252
|
-
|
|
253
|
-
<div align="center">
|
|
254
|
-
|
|
255
|
-
**Built with ❤️ for safer, more efficient maritime operations**
|
|
256
|
-
|
|
257
|
-
⭐ Star this repo if you find it useful!
|
|
258
|
-
|
|
259
|
-
</div>
|
|
File without changes
|
|
File without changes
|