Rectangle Packer

2.1.0 · active · verified Fri Apr 17

rectangle-packer is a Python library for efficiently packing a set of 2D rectangles into a minimal bounding box. It utilizes an optimized best-fit heuristic algorithm to achieve high packing density. The current stable version is 2.1.0, and it maintains a moderate release cadence, with updates addressing performance and edge cases, primarily focusing on its core `pack` functionality.

Common errors

```
AttributeError: module 'rpack' has no attribute 'group'
```
cause The `rpack.group` function was removed in version 2.0.6. It was part of an older API for packing multiple groups of rectangles.

fix Upgrade to `rectangle-packer` version 2.0.6 or newer and use `rpack.pack` directly. If you need to pack independent sets of rectangles, call `rpack.pack` for each set.
```
ImportError: cannot import name '_rpack' from 'rpack'
```
cause The internal `_rpack` extension module was removed in version 2.0.6 as part of API simplification and consolidation.

fix Upgrade to `rectangle-packer` version 2.0.6 or newer. The core packing functionality is now directly exposed via `rpack.pack`. Avoid importing internal modules directly.
```
OverflowError: Python int too large to convert to C long
```
cause This error occurs in versions prior to 2.1.0 when `rpack.pack` is given rectangles with extremely large width or height values that exceed the capacity of the underlying C `long` integer type.

fix Upgrade to `rectangle-packer` version 2.1.0 or newer. This version includes robust bigint preprocessing to handle large Python integers correctly without overflow.

Warnings

breaking The `rpack.group` function and the internal `rpack._rpack` extension module were removed in version 2.0.6. These were part of the older API and have been consolidated.
Fix: Migrate any usage of `rpack.group` or direct calls to `rpack._rpack.pack` to use `rpack.pack` directly. The `pack` function is now the sole public API for packing.
gotcha Prior to version 2.1.0, packing rectangles with extremely large width/height values (exceeding standard C `long` limits) could lead to `OverflowError` or incorrect results due to integer overflow in the underlying C extension.
Fix: Upgrade to version 2.1.0 or newer. This version introduced bigint preprocessing, including `gcd` normalization and power-of-two scaling, to robustly handle very large Python integers.
gotcha Performance and packing density for 'thin' or 'pathological' rectangle inputs (e.g., 1x1000) were less optimal in versions prior to 2.1.0.
Fix: Upgrade to version 2.1.0 or newer. This version significantly improved `rpack.pack()` search behavior for such inputs by adding staged coarse candidate stepping with bounded local refinement.

Install

pip install rectangle-packer Install stable version

Imports

pack
```
from rpack import pack
```
group
wrong:
```
from rpack import group
```
correct:
```
from rpack import pack # 'group' was removed
```
The 'group' function was removed in version 2.0.6. Use 'rpack.pack' directly.
_rpack
wrong:
```
import rpack._rpack
```
correct:
```
from rpack import pack # '_rpack' was removed
```
The internal '_rpack' extension module was removed in version 2.0.6. Use 'rpack.pack' directly.

Quickstart

This quickstart demonstrates how to define a list of rectangles as (width, height) tuples and use `rpack.pack()` to find their optimal positions within a minimal bounding box. It then prints the calculated (x, y) positions for each rectangle and the overall dimensions of the packed area.

import rpack

# Rectangles are defined as (width, height) tuples
rects = [
    (10, 20),
    (5, 15),
    (12, 12),
    (30, 10),
    (8, 25)
]

# Pack the rectangles, returns a list of (x, y) positions
# (0,0) is top-left, increasing x to the right, increasing y downwards
positions = rpack.pack(rects)

# The positions correspond to the input rectangles order
for i, (x, y) in enumerate(positions):
    print(f"Rectangle {i+1} (w={rects[i][0]}, h={rects[i][1]}): Position ({x}, {y})")

# You can find the enclosing dimensions of the packed layout
width, height = rpack.util.enclosing_size(rects, positions)
print(f"Total enclosing size: Width={width}, Height={height}")

view raw JSON →