<img alt="Version" src="https://img.shields.io/badge/version-1.0.0--beta-blue.svg?cacheSeconds=604800" />
<a href="https://github.com/Gato-X/python-LinkedTuple/blob/main/LICENSE" target="_blank"><img alt="License:BSD" src="https://img.shields.io/badge/License-BSD-yellow.svg" /></a>
# packer2d
# Project Description
The primary goal of 2D bin packing is to discover an arrangement of items (in this case, rectangles) that optimally utilizes the available container space.
This is precisely what Packer2D does. It takes a list of rectangles and arranges their positions within a specified rectangular area, aiming to pack them efficiently and minimize wasted space.
# Installation
## Using pip
```
pip install packer2d
```
## From sources
The source code is available at [Gitlab](https://gitlab.com/felingineer/packer2d)
# Example
```python
from packer2d import Item, pack
# let's say we have this list with the sizes of the rectangles to pack
sizes = [
(15,20),
(7,5),
(9,18),
...
]
# The packer function takes a list of Item objects, so we create it now.
# We can initialize Item objects with 2-tuples that contain the size of the rectangles
# or with 4-tuples that specify the corners of the rectangle like so: (x1, y2, x2, y2).
# In that case, only their size is taken into consideration, as they will be moved around.
items = [Item(size) for size in sizes]
pack(items, (200, 200))
# now the rect propery of each item has been set to a Rect object, which can be seen as
# a 4-tuple with the coordinates (x1, y2, x2, y2).
for item in items:
print(item.rect)
```
There's another example in the repository, called `test.py`, which was used to generate the image shown at the top. It requires the package `pillow` to be installed.
# API
## FUNCTIONS
### ➤ function *pack*
```python
pack(
items: Iterable[Item],
max_area: Tuple,
arrange: Optional[Callable, Arrange] = None,
insert_order: Optional[Callable, PlaceOrder] = None,
smallest_size: Union[int, Tuple[int, int]] = 3,
max_depth: int = 5,
int_coords: bool = True,
grow_dir: GrowDirection = <GrowDirection.ANYWHERE: 3>
) → QTree
```
Packs a list of 2D items into a given area. After the function has been called, the location of the items has been computed and their rect field has been updated.
#### Args:
- **items** (list): A list of Item objects to be packed into the area.
Required parameter.
- **max_area** (tuple): The maximum area to pack the items into. It can be either a (width, height) or a (x1, y1, x2, y2) tuple. Note the area might grow beyond the initial size if `grow_dir` is set.
Required parameter.
- **arrange** (function or str, optional): How will the items be laid out in the area:
* If not set, or "top", items will be laid out from top to bottom.
* If "left", items will be placed from left to right.
* If it's a function, then it must accept two parameters and must either return a rectangle where the item should be placed, or raise **NotEnoughSpaceError** if a suitable area couldn't be found. Such a function can be created with `getArrangeFn`.
Args:
- **qt** (QTree): The quadtree containing the available areas.
- **item** (Item): The item to be placed.
Defaults to "top"
- **insert_order** (function or str, optional): The function to determine the order in which items are inserted:
* If not set to "largest_first", items will be inserted from largest to smallest.
* If "smallest_first", items will be inserted from smallest to largest.
* If it's a function, then it must accept an Item as only parameter and must return a value usable as key when sorting a list. Its value will determine the order in which items are considered for placement. Such a function can be created with `rectSortFn`.
Defaults to "largest_first".
- **smallest_size** (tuple or int, optional): Free areas smaller than this size won't be considered. Setting this value too low can make the packing slower. Setting it too high may cause too much wasted space. It should match the smallest size of the item to be placed.
Defaults to 3 (which is equivalent to (3,3) )
- **max_depth** (int, optional): The maximum depth of the quadtree. Note if growing the area is allowed (by using `grow_dir`), then max_depth automatically increments whenever the area is expanded.
Defaults to 5.
- **int_coords** (bool, optional): Whether to enforce integer coordinates for the item placement.
Defaults to True.
- **grow_dir** (GrowDirection, optional): The direction in which the container can grow if it doesn't have enough space to contain all the items.
If set to "nowhere", no attempt will be made to grow the container and an exception will be raised if there's not enough space.
Defaults to "anywhere".
#### Returns:
- QTree : An instance of the internal quadtree used to keep track of available areas.
#### Raises:
- **NotEnoughSpaceError** if not all elements can be placed in *max_area* and grow_dir was set to "nowhere".
</br></br>
### ➤ function *getArrangeFn*
```python
getArrangeFn(orientation: ArrangeType, param: float = None) → Callable
```
Creates and returns a function used to pick the best location to place an item, from all available locations at a given moment.
#### Args:
- **orientation** (str): The orientation of the rectangles. Must be either "left", "top" or "box".
- **param** (float): Used when orientation=="box" to specify the aspect ratio of the placement. If 1 or not specified, then it is a square.
#### Returns:
- A function (see the parameter `arrange` in the function `pack`)
#### Raises:
- **ValueError** If the orientation is not "left", "top" or "box".
</br></br>
### ➤ function *getRectSortFn*
```python
getRectSortFn(order: PlaceOrderType) → Callable
```
Creates and returns a function that can be passed as key when sorting a list. It's used to decide the order in which items get placed.
#### Args:
- **order** (str): The order in which to sort the rectangles. Must be either "largest_first" or "smallest_first".
#### Returns:
- A function (see parameter `insert_order` in the function `pack`)
#### Raises:
- **ValueError** If the order is neither 'biggest_first' or 'smallest_first'.
</br></br>
## CLASSES
### ➤ class *Item*
Container that holds a rectangle and an optional data field. It is used to pass the rectangles that will be arranged to the function `pack`. It is also used internally by the packer to store the available regions in a QTree.
#### `__init__(self, rect: Union[Tuple, RectType], data: Any = None)`
- **rect** (tuple or RectType): Can be a 2-tuple with the size of the item (width, height), a 4-tuple with the coordinates of the item (x1, y1, x2, y2) or an object that fulfills the `RectType` requirements.
- **data** (any): Can be set by the user to anything
#### Properties:
- **rect** (RectType): This is set from the passed argument of the same name when creating an instance. However, in this case it is guaranteed to be a `RectType` object. If the object passed to the constructor wasn't one, a Rect object is created from it.
- **data** (any): Whatever was passed in the constructor, or None if not set.
</br></br>
### ➤ class *Rect*
A subclass of namedtuple that contains the fields x1, y1, x2, y2.
#### `__init__(self, x1:IntFloatType, y1:IntFloatType, x2:IntFloatType, y2:IntFloatType)`
#### Properties (read only):
- **x1** (IntFloatType)
- **y1** (IntFloatType)
- **x2** (IntFloatType)
- **y2** (IntFloatType)
</br></br>
## TYPES
### ➤ *FloatIntType*
A type that is either float or int
### ➤ *GrowDirectionType*
One of the following strings: "nowhere", "anywhere", "vertical", "horizontal"
### ➤ *ArrangeType*
One of the following strings: "box", "left", "top"
### ➤ *PlaceOrderType*
One of the following strings: "smallest_first", "largest_first"
### ➤ *RectType*
A type for an object that has the attributes `x1`, `y2`, `x2`, `y2`, of type either int or float
</br></br>
## EXCEPTIONS
### ➤ *NotEnoughSpaceError*
Raised when there is not enough space in the provided area to pack all the items, and growing of the area was not allowed.
</br></br>
# Licensing and Copyright
BSD 2-Clause License
Copyright © 2023, Guillermo Romero (Gato)
Raw data
{
"_id": null,
"home_page": "https://gitlab.com/felingineer/packer2d",
"name": "packer2d",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "BIN,PACKING,2D",
"author": "Guillermo Romero (Gato)",
"author_email": "gato@felingineering.com",
"download_url": "https://files.pythonhosted.org/packages/7b/eb/52b2577a028e97bd1111eb5992efdcd230c4283eb91c4b92fb6bd8014ad6/packer2d-1.0.0b0.tar.gz",
"platform": null,
"description": "<img alt=\"Version\" src=\"https://img.shields.io/badge/version-1.0.0--beta-blue.svg?cacheSeconds=604800\" />\n<a href=\"https://github.com/Gato-X/python-LinkedTuple/blob/main/LICENSE\" target=\"_blank\"><img alt=\"License:BSD\" src=\"https://img.shields.io/badge/License-BSD-yellow.svg\" /></a>\n\n# packer2d\n\n\n# Project Description\n \nThe primary goal of 2D bin packing is to discover an arrangement of items (in this case, rectangles) that optimally utilizes the available container space.\n\nThis is precisely what Packer2D does. It takes a list of rectangles and arranges their positions within a specified rectangular area, aiming to pack them efficiently and minimize wasted space.\n\n\n\n\n# Installation\n\n## Using pip\n\n```\npip install packer2d\n\n```\n\n## From sources\n\nThe source code is available at [Gitlab](https://gitlab.com/felingineer/packer2d)\n\n# Example\n\n```python\n\nfrom packer2d import Item, pack\n\n# let's say we have this list with the sizes of the rectangles to pack\n\nsizes = [\n (15,20),\n (7,5),\n (9,18),\n ...\n]\n\n# The packer function takes a list of Item objects, so we create it now.\n# We can initialize Item objects with 2-tuples that contain the size of the rectangles\n# or with 4-tuples that specify the corners of the rectangle like so: (x1, y2, x2, y2).\n# In that case, only their size is taken into consideration, as they will be moved around.\n\nitems = [Item(size) for size in sizes]\n\npack(items, (200, 200))\n\n# now the rect propery of each item has been set to a Rect object, which can be seen as\n# a 4-tuple with the coordinates (x1, y2, x2, y2). \n\nfor item in items:\n print(item.rect)\n\n\n```\n\nThere's another example in the repository, called `test.py`, which was used to generate the image shown at the top. It requires the package `pillow` to be installed.\n\n\n\n# API\n\n\n## FUNCTIONS\n\n### \u27a4 function *pack*\n\n```python\npack(\n items: Iterable[Item],\n max_area: Tuple,\n arrange: Optional[Callable, Arrange] = None,\n insert_order: Optional[Callable, PlaceOrder] = None,\n smallest_size: Union[int, Tuple[int, int]] = 3,\n max_depth: int = 5,\n int_coords: bool = True,\n grow_dir: GrowDirection = <GrowDirection.ANYWHERE: 3>\n) \u2192 QTree\n```\n\nPacks a list of 2D items into a given area. After the function has been called, the location of the items has been computed and their rect field has been updated. \n\n\n\n#### Args:\n\n - **items** (list): A list of Item objects to be packed into the area. \n\n Required parameter.\n\n\n - **max_area** (tuple): The maximum area to pack the items into. It can be either a (width, height) or a (x1, y1, x2, y2) tuple. Note the area might grow beyond the initial size if `grow_dir` is set.\n\n Required parameter.\n\n\n - **arrange** (function or str, optional): How will the items be laid out in the area:\n \n * If not set, or \"top\", items will be laid out from top to bottom. \n \n * If \"left\", items will be placed from left to right. \n \n * If it's a function, then it must accept two parameters and must either return a rectangle where the item should be placed, or raise **NotEnoughSpaceError** if a suitable area couldn't be found. Such a function can be created with `getArrangeFn`.\n\n Args:\n \n - **qt** (QTree): The quadtree containing the available areas.\n \n - **item** (Item): The item to be placed.\n\n Defaults to \"top\"\n\n\n - **insert_order** (function or str, optional): The function to determine the order in which items are inserted: \n * If not set to \"largest_first\", items will be inserted from largest to smallest. \n \n * If \"smallest_first\", items will be inserted from smallest to largest. \n \n * If it's a function, then it must accept an Item as only parameter and must return a value usable as key when sorting a list. Its value will determine the order in which items are considered for placement. Such a function can be created with `rectSortFn`.\n\n Defaults to \"largest_first\".\n\n - **smallest_size** (tuple or int, optional): Free areas smaller than this size won't be considered. Setting this value too low can make the packing slower. Setting it too high may cause too much wasted space. It should match the smallest size of the item to be placed. \n\n Defaults to 3 (which is equivalent to (3,3) )\n \n - **max_depth** (int, optional): The maximum depth of the quadtree. Note if growing the area is allowed (by using `grow_dir`), then max_depth automatically increments whenever the area is expanded. \n\n Defaults to 5.\n \n - **int_coords** (bool, optional): Whether to enforce integer coordinates for the item placement. \n\n Defaults to True. \n\n - **grow_dir** (GrowDirection, optional): The direction in which the container can grow if it doesn't have enough space to contain all the items. \n If set to \"nowhere\", no attempt will be made to grow the container and an exception will be raised if there's not enough space. \n \n Defaults to \"anywhere\". \n\n#### Returns:\n \n - QTree : An instance of the internal quadtree used to keep track of available areas.\n\n#### Raises:\n\n - **NotEnoughSpaceError** if not all elements can be placed in *max_area* and grow_dir was set to \"nowhere\".\n\n</br></br>\n\n### \u27a4 function *getArrangeFn*\n\n```python\ngetArrangeFn(orientation: ArrangeType, param: float = None) \u2192 Callable\n```\n\nCreates and returns a function used to pick the best location to place an item, from all available locations at a given moment.\n\n#### Args:\n\n - **orientation** (str): The orientation of the rectangles. Must be either \"left\", \"top\" or \"box\". \n\n\n - **param** (float): Used when orientation==\"box\" to specify the aspect ratio of the placement. If 1 or not specified, then it is a square.\n\n\n#### Returns:\n\n - A function (see the parameter `arrange` in the function `pack`)\n\n\n#### Raises:\n\n - **ValueError** If the orientation is not \"left\", \"top\" or \"box\".\n\n</br></br>\n\n### \u27a4 function *getRectSortFn*\n\n```python\ngetRectSortFn(order: PlaceOrderType) \u2192 Callable\n```\n\nCreates and returns a function that can be passed as key when sorting a list. It's used to decide the order in which items get placed.\n\n\n\n#### Args:\n - **order** (str): The order in which to sort the rectangles. Must be either \"largest_first\" or \"smallest_first\". \n\n\n\n#### Returns:\n\n - A function (see parameter `insert_order` in the function `pack`)\n\n\n#### Raises:\n\n\n - **ValueError** If the order is neither 'biggest_first' or 'smallest_first'. \n\n</br></br>\n\n## CLASSES\n\n### \u27a4 class *Item*\nContainer that holds a rectangle and an optional data field. It is used to pass the rectangles that will be arranged to the function `pack`. It is also used internally by the packer to store the available regions in a QTree.\n\n\n#### `__init__(self, rect: Union[Tuple, RectType], data: Any = None)`\n\n - **rect** (tuple or RectType): Can be a 2-tuple with the size of the item (width, height), a 4-tuple with the coordinates of the item (x1, y1, x2, y2) or an object that fulfills the `RectType` requirements.\n\n - **data** (any): Can be set by the user to anything\n\n\n#### Properties:\n\n - **rect** (RectType): This is set from the passed argument of the same name when creating an instance. However, in this case it is guaranteed to be a `RectType` object. If the object passed to the constructor wasn't one, a Rect object is created from it.\n\n - **data** (any): Whatever was passed in the constructor, or None if not set.\n \n</br></br>\n\n### \u27a4 class *Rect*\nA subclass of namedtuple that contains the fields x1, y1, x2, y2.\n\n#### `__init__(self, x1:IntFloatType, y1:IntFloatType, x2:IntFloatType, y2:IntFloatType)`\n\n#### Properties (read only):\n\n - **x1** (IntFloatType)\n\n - **y1** (IntFloatType)\n\n - **x2** (IntFloatType)\n\n - **y2** (IntFloatType)\n\n</br></br>\n\n## TYPES\n\n### \u27a4 *FloatIntType*\n\nA type that is either float or int\n\n### \u27a4 *GrowDirectionType*\nOne of the following strings: \"nowhere\", \"anywhere\", \"vertical\", \"horizontal\"\n\n### \u27a4 *ArrangeType*\nOne of the following strings: \"box\", \"left\", \"top\"\n\n### \u27a4 *PlaceOrderType*\nOne of the following strings: \"smallest_first\", \"largest_first\"\n\n### \u27a4 *RectType*\n\nA type for an object that has the attributes `x1`, `y2`, `x2`, `y2`, of type either int or float\n\n\n</br></br>\n\n## EXCEPTIONS\n\n\n### \u27a4 *NotEnoughSpaceError*\nRaised when there is not enough space in the provided area to pack all the items, and growing of the area was not allowed.\n\n\n</br></br>\n\n# Licensing and Copyright \n\nBSD 2-Clause License\n\nCopyright \u00a9 2023, Guillermo Romero (Gato)\n\n\n\n\n\n",
"bugtrack_url": null,
"license": "BSD-2-Clause",
"summary": "2D bin packer",
"version": "1.0.0b0",
"project_urls": {
"Download": "https://gitlab.com/felingineer/packer2d",
"Homepage": "https://gitlab.com/felingineer/packer2d"
},
"split_keywords": [
"bin",
"packing",
"2d"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b4966a0e3e8cf51a8147ae8571eed5e9678936b2b792bd5f04a0223448262225",
"md5": "879bd5880ce2bf586c36e7be28302726",
"sha256": "12e87d7354d3755acc4d3cec1605fdc11b8c02b1d6390043a66d8bcf7c803a3a"
},
"downloads": -1,
"filename": "packer2d-1.0.0b0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "879bd5880ce2bf586c36e7be28302726",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 14942,
"upload_time": "2023-10-26T02:59:08",
"upload_time_iso_8601": "2023-10-26T02:59:08.886472Z",
"url": "https://files.pythonhosted.org/packages/b4/96/6a0e3e8cf51a8147ae8571eed5e9678936b2b792bd5f04a0223448262225/packer2d-1.0.0b0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7beb52b2577a028e97bd1111eb5992efdcd230c4283eb91c4b92fb6bd8014ad6",
"md5": "39c63fdb2442dd68c4a65b2ce007fde7",
"sha256": "95cf43c402fc7306645947b230e938c096e4fcd7a7e4bbc404b4bb6576e2c1b7"
},
"downloads": -1,
"filename": "packer2d-1.0.0b0.tar.gz",
"has_sig": false,
"md5_digest": "39c63fdb2442dd68c4a65b2ce007fde7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 16387,
"upload_time": "2023-10-26T02:59:10",
"upload_time_iso_8601": "2023-10-26T02:59:10.708227Z",
"url": "https://files.pythonhosted.org/packages/7b/eb/52b2577a028e97bd1111eb5992efdcd230c4283eb91c4b92fb6bd8014ad6/packer2d-1.0.0b0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-26 02:59:10",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "felingineer",
"gitlab_project": "packer2d",
"lcname": "packer2d"
}
JSON