{"id":18141532,"url":"https://github.com/skjolber/3d-bin-container-packing","last_synced_at":"2025-05-15T00:12:35.483Z","repository":{"id":37413195,"uuid":"56717384","full_name":"skjolber/3d-bin-container-packing","owner":"skjolber","description":"A variant of the Largest Area Fit First (LAFF) algorithm + brute force algorithm","archived":false,"fork":false,"pushed_at":"2025-04-05T22:11:36.000Z","size":4490,"stargazers_count":459,"open_issues_count":42,"forks_count":128,"subscribers_count":15,"default_branch":"master","last_synced_at":"2025-04-06T18:11:22.507Z","etag":null,"topics":["2d-bin-packing","3d-bin-packing","bin-packing","brute-force","deadline","java"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/skjolber.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-04-20T20:03:45.000Z","updated_at":"2025-03-28T19:51:35.000Z","dependencies_parsed_at":"2023-10-13T13:32:57.887Z","dependency_job_id":"9c89bcdf-3490-48d6-ada4-a5dfcc35a46b","html_url":"https://github.com/skjolber/3d-bin-container-packing","commit_stats":{"total_commits":929,"total_committers":14,"mean_commits":66.35714285714286,"dds":0.5705059203444565,"last_synced_commit":"66e9723fd65b89195046a447f2af1e3d6857f298"},"previous_names":[],"tags_count":58,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skjolber%2F3d-bin-container-packing","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skjolber%2F3d-bin-container-packing/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skjolber%2F3d-bin-container-packing/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skjolber%2F3d-bin-container-packing/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/skjolber","download_url":"https://codeload.github.com/skjolber/3d-bin-container-packing/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248782282,"owners_count":21160716,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["2d-bin-packing","3d-bin-packing","bin-packing","brute-force","deadline","java"],"created_at":"2024-11-01T17:07:28.814Z","updated_at":"2025-05-15T00:12:35.471Z","avatar_url":"https://github.com/skjolber.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Build Status](https://github.com/skjolber/3d-bin-container-packing/actions/workflows/maven.yml/badge.svg) \n[![Maven Central](https://img.shields.io/maven-central/v/com.github.skjolber.3d-bin-container-packing/parent.svg)](https://mvnrepository.com/artifact/com.github.skjolber.3d-bin-container-packing)\n\n# 3d-bin-container-packing\n\nThis library does 3D rectangular bin packing; it attempts to match a set of 3D items to one or more in a set of 3D containers. The result can be constrained to a maximum number of containers.\n\nProjects using this library will benefit from:\n * short and predictable calculation time,\n * fairly good use of container space, \n * brute-force support for low number of boxes (ideal for small orders)\n    \nBugs, feature suggestions and help requests can be filed with the [issue-tracker].\n\n## Obtain\nThe project is implemented in Java and built using [Maven]. The project is available on the central Maven repository.\n\n\u003cdetails\u003e\n  \u003csummary\u003eMaven coordinates\u003c/summary\u003e\n\nAdd\n \n```xml\n\u003c3d-bin-container-packing.version\u003e3.0.9\u003c/3d-bin-container-packing.version\u003e\n```\n\nand\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003ecom.github.skjolber.3d-bin-container-packing\u003c/groupId\u003e\n    \u003cartifactId\u003ecore\u003c/artifactId\u003e\n    \u003cversion\u003e${3d-bin-container-packing.version}\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n\u003c/details\u003e\n\nor\n\n\u003cdetails\u003e\n  \u003csummary\u003eGradle coordinates\u003c/summary\u003e\n\nFor\n\n```groovy\next {\n  containerBinPackingVersion = '3.0.9'\n}\n```\n\nadd\n\n```groovy\napi(\"com.github.skjolber.3d-bin-container-packing:core:${containerBinPackingVersion}\")\n```\n\n\u003c/details\u003e\n\nJava 11+ projects please use module `com.github.skjolber.packing.core`.\n\n# Usage\nThe units of measure is out-of-scope, be they cm, mm or inches.\n\nObtain a `Packager` instance, then then compose your container and product list:\n\n```java\nList\u003cStackableItem\u003e products = new ArrayList\u003cStackableItem\u003e();\n\nproducts.add(new StackableItem(Box.newBuilder().withId(\"Foot\").withSize(6, 10, 2).withRotate3D().withWeight(25).build(), 1));\nproducts.add(new StackableItem(Box.newBuilder().withId(\"Leg\").withSize(4, 10, 1).withRotate3D().withWeight(25).build(), 1));\nproducts.add(new StackableItem(Box.newBuilder().withId(\"Arm\").withSize(4, 10, 2).withRotate3D().withWeight(50).build(), 1));\n\n// add a single container type\nContainer container = Container.newBuilder()\n    .withDescription(\"1\")\n    .withSize(10, 10, 3)\n    .withEmptyWeight(1)\n    .withMaxLoadWeight(100)\n    .build();\n    \n// with unlimited number of containers available\nList\u003cContainerItem\u003e containerItems = ContainerItem\n    .newListBuilder()\n    .withContainer(container)\n    .build();\n```\n\nPack all in a single container:\n\n```java\nPackagerResult result = packager\n    .newResultBuilder()\n    .withContainers(containerItems)\n    .withStackables(products)\n    .build();\n\nif(result.isSuccess()) {\n    Container match = result.get(0);\n    \n    // ...\n}\n```\n\nPack all in a maximum number of containers:\n\n```java\nint maxContainers = ...; // maximum number of containers which can be used\n\nPackagerResult result = packager\n    .newResultBuilder()\n    .withContainers(containerItems)\n    .withStackables(products)\n    .withMaxContainerCount(maxContainers)\n    .build();\n```\n\nNote that all `packager` instances are thread-safe.\n\n### Plain packager\nA simple packager\n\n```java\nPlainPackager packager = PlainPackager\n    .newBuilder()\n    .build();\n```\n\n### Largest Area Fit First (LAFF) packager\nA packager using the LAFF algorithm\n\n```java\nLargestAreaFitFirstPackager packager = LargestAreaFitFirstPackager\n    .newBuilder()\n    .build();\n```\n\n### Brute-force packager\nFor a low number of packages (like \u003c= 6) the brute force packager might be a good fit. \n\n```java\nPackager packager = BruteForcePackager\n    .newBuilder()\n    .build();\n```\n\nUsing a deadline is recommended whenever brute-forcing in a real-time application.\n\n\u003cdetails\u003e\n  \u003csummary\u003eAlgorithm details\u003c/summary\u003e\n \n### Largest Area Fit First algorithm\nThe implementation is based on [this paper][2], and is not a traditional [bin packing problem][1] solver.\n\nThe box which covers the largest ground area of the container is placed first; its height becomes the level height. Boxes which fill the full remaining height take priority. Subsequent boxes are stacked in the remaining space in at the same level, the boxes with the greatest volume first. If box height is lower than level height, the algorithm attempts to place some there as well. \n\nWhen no more boxes fit in a level, the level is incremented and the process repeated. Boxes are rotated, containers not.\n\n * `LargestAreaFitFirstPackager` stacks in 3D within each level\n * `FastLargestAreaFitFirstPackager` stacks in 2D within each level\n\nThe algorithm runs reasonably fast, usually in milliseconds. Some customization is possible.\n\n### Plain algorithm\nThis algorithm selects the box with the biggest volume, fitting it where it is best supported.\n\n###  Brute-force algorithm\nThis algorithm has no logic for selecting the best box or rotation; running through all permutations, for each permutation all rotations:\n\n * `BruteForcePackager` attempts all box orders, rotations and placement positions.\n * `FastLargestAreaFitFirstPackager` selects all box orders and rotations, selecting the most appropriate placement position.\n\nThe complexity of this approach is [exponential], and thus there is a limit to the feasible number of boxes which can be packaged within a reasonable time. However, for real-life applications,  a healthy part of for example online shopping orders are within its grasp.\n\nThe worst case complexity can be estimated using the `DefaultPermutationRotationIterator` before packaging is attempted.\n\nThe algorithm tries to skip combinations which will obviously not yield a (better) result:\n\n * permutations\n   * two or more boxes have the same dimensions\n   * permutations which mutated at a previously unreachable index\n * fewer rotations\n   * two or more sides have the same length\n   * rotations which mutated at a previously unreachable index\n \nThere is also a parallel version `ParallelBruteForcePackager` of the brute-force packager, for those wishing to use it on a multi-core system.\n\nNote that the algorithm is recursive on the number of boxes, so do not attempt this with many boxes (it will likely not complete in time anyhow).\n\n\u003c/details\u003e \n \n### Visualizer\nThere is a simple output [visualizer](visualization) included in this project, based of [three.js](https://threejs.org/). This visualizer is currently intended as a tool for developing better algorithms (not as stacking instructions).\n\n![Alt text](visualizer/viewer/images/view.png?raw=true \"Demo\")\n\nTo use the visualizer during development, make your unit tests write directly to a file in the project (see `VisualizationTest` example). \n\n# Customization\nThe code has been structured so it is possible to extend and adapt to specialized needs. See `AbstractPackager` class, the `extreme-points` and `test` artifacts. \n\n# Get involved\nIf you have any questions, comments or improvement suggestions, please file an issue or submit a pull-request. \n\nNote on bugs: Please follow [shuairan's](https://github.com/shuairan) example and [file a test case with a visualization](https://github.com/skjolber/3d-bin-container-packing/issues/574).\n\nFeel free to connect with me on [LinkedIn], see also my [Github page].\n\n## License\n[Apache 2.0]. Social media preview by [pch.vector on www.freepik.com](https://www.freepik.com/free-photos-vectors/people).\n\n# Interesting links\n\n * [The Art of Stacking: Challenges Faced While Developing a Packing Algorithm](https://medium.com/@fayyazawais1412/the-art-of-stacking-challenges-faced-while-developing-a-packing-algorithm-64d869b924ab)\n\n# History\n * 3.0.10: Fix module info, bump dependencies.\n * 3.0.9: Fix point support bug which resulted in invalid packaging result\n * 3.0.8: Visualization fix\n * 3.0.4-3.0.6: Fix issue #689\n * 3.0.3: Fix module info\n * 3.0.2: Make Plain Packager prefer low z coordinate over supported area.\n * 3.0.1: Various performance improvements.\n * 3.0.0: Support max number of containers (i.e. per container type). Use builders from now on. Various optimizations.\n * 2.1.4: Fix issue #574\n * 2.1.3: Fix nullpointer\n * 2.1.2: Tidy up, i.e. remove warnings, nuke some dependencies.\n * 2.1.1: Improve free space calculation performance\n * 2.1.0: Improve brute force iterators, respect deadlines in brute for packagers.\n\n[1]: \t\t\t\thttps://en.wikipedia.org/wiki/Bin_packing_problem\n[2]: \t\t\t\thttps://www.drupal.org/files/An%20Efficient%20Algorithm%20for%203D%20Rectangular%20Box%20Packing.pdf\n[Apache 2.0]: \t\thttp://www.apache.org/licenses/LICENSE-2.0.html\n[issue-tracker]:\thttps://github.com/skjolber/3d-bin-container-packing/issues\n[Maven]:\t\t\thttp://maven.apache.org/\n[LinkedIn]:\t\t\thttp://lnkd.in/r7PWDz\n[Github page]:\t\thttps://skjolber.github.io\n[NothinRandom]:\t\thttps://github.com/NothinRandom\n[exponential]:\t\thttps://en.wikipedia.org/wiki/Exponential_function\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fskjolber%2F3d-bin-container-packing","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fskjolber%2F3d-bin-container-packing","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fskjolber%2F3d-bin-container-packing/lists"}