fastrectpack 0.1.0__tar.gz

fastrectpack-0.1.0/.clang-format

@@ -0,0 +1,5 @@
+BasedOnStyle: Google
+IndentWidth: 4
+AccessModifierOffset: -4
+ColumnLimit: 120
+AllowShortIfStatementsOnASingleLine: WithoutElse

fastrectpack-0.1.0/.editorconfig

@@ -0,0 +1,15 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+
+[*.{yml,yaml,toml,json}]
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false

fastrectpack-0.1.0/.gitattributes

@@ -0,0 +1,2 @@
+* text=auto eol=lf
+*.png binary

fastrectpack-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+*.pyc
+build/
+dist/
+*.egg-info/
+.hypothesis/
+.pytest_cache/
+.venv*/

fastrectpack-0.1.0/BENCHMARKS.md

@@ -0,0 +1,92 @@
+# Benchmarks
+
+## Reproduce
+
+```
+pip install .
+python bench/run_bench.py            # writes results/bench.json and results/bench.md
+python tools/summarize.py            # writes results/summary.md from every results/bench*.json
+```
+
+`--quick` runs five small cases in about a minute. On Windows the script restricts itself to logical CPUs 0-13 by default (`--cpus all` turns that off); see [Noise](#noise-on-this-machine).
+
+## Environment
+
+| | |
+|---|---|
+| Machine | Laptop, Intel Core i7-14700HX (20 cores, 28 threads; hybrid: fast and slow cores), 31.7 GB RAM |
+| OS | Windows 11 Home, build 10.0.26100, "Balanced" power plan |
+| Python | CPython 3.13.5 (Anaconda build, MSC v.1929, 64-bit) |
+| Compiler | MSVC 19.44 (Visual Studio 2022), Release configuration, default optimisation flags |
+| Original library | rectpack 0.2.2 |
+| Build tools | pybind11 3.1.0, CMake 4.4.4, scikit-build-core (exact versions in `results/pip_freeze.txt`) |
+| Date | 2026-11-10 |
+
+## What is measured
+
+- **Operation:** build a packer with `newPacker()` defaults (offline mode, best-bin-fit, `MaxRectsBssf`, sort by area, rotation on), add all rectangles and bins, call `pack()`, read `rect_list()`. The whole call is timed, including Python-side setup.
+- **Three variants, same inputs:**
+  1. `original`: rectpack 0.2.2, untouched.
+  2. `python_fixes`: the original with two pure-Python changes and no C++ (`bench/cheap_wins.py`).
+  3. `native`: fastrectpack.
+- **Workloads** (`bench/workloads.py`, fixed seeds, integer sizes):
+  - `random`: sides uniform in 10-100, bins 1000x1000.
+  - `cutting`: 20 typical sheet-part sizes with heavy repetition, bins 2440x1220. Uses many bins.
+  - `sprites`: sides drawn from 16 to 256 in the usual texture steps, bins 2048x2048.
+  - `skewed`: 5% large pieces (200-600), the rest small (5-60), bins 1500x1500.
+- **Procedure:** the variants are run interleaved in rotating order, so background load affects them alike. One warm-up round for cases up to 1,000 rectangles. Rounds: 7 up to 1,000 rectangles, 5 at 2,000, 3 at 5,000. Garbage is collected before each timed call.
+- **Statistic:** best (minimum) time per variant, and speedup = best original time / best variant time. Background load only ever adds time, so the minimum is the closest estimate of the code's own cost. The table also shows the range of per-round speedups from the main run.
+- **Parity:** each run hashes the full output of all three variants. A mismatch fails the script.
+
+## Results
+
+Generated by `tools/summarize.py` into `results/summary.md`. "Best" is the minimum over every run recorded on this machine, which for the original is the least flattering choice for the speedup.
+
+| Workload | Rectangles | Bins used | Original (best) | Python fixes (best) | C++ (best) | Speedup, Python fixes | Speedup, C++ | C++ speedup range across rounds of the main run | Output identical |
+|---|---|---|---|---|---|---|---|---|---|
+| random | 200 | 1 | 0.344 s | 0.114 s | 0.0032 s | 3.0x | 106x | 99x to 108x | yes |
+| random | 500 | 2 | 0.944 s | 0.168 s | 0.0057 s | 5.6x | 164x | 69x to 165x | yes |
+| random | 1,000 | 4 | 3.525 s | 0.473 s | 0.0144 s | 7.5x | 246x | 198x to 264x | yes |
+| random | 2,000 | 7 | 7.703 s | 1.071 s | 0.0792 s | 7.2x | 97x | 115x to 219x | yes |
+| random | 5,000 | 16 | 21.123 s | 3.738 s | 0.1364 s | 5.7x | 155x | 121x to 265x | yes |
+| cutting | 500 | 27 | 0.036 s | 0.022 s | 0.0068 s | 1.7x | 5x | 5x to 5x | yes |
+| cutting | 1,000 | 50 | 0.119 s | 0.066 s | 0.0221 s | 1.8x | 5x | 5x to 6x | yes |
+| cutting | 2,000 | 100 | 0.415 s | 0.214 s | 0.0780 s | 1.9x | 5x | 5x to 6x | yes |
+| sprites | 500 | 2 | 0.069 s | 0.032 s | 0.0029 s | 2.1x | 23x | 24x to 26x | yes |
+| sprites | 1,000 | 3 | 0.487 s | 0.131 s | 0.0075 s | 3.7x | 65x | 67x to 70x | yes |
+| sprites | 2,000 | 5 | 1.500 s | 0.322 s | 0.0177 s | 4.7x | 85x | 85x to 88x | yes |
+| skewed | 500 | 3 | 0.684 s | 0.120 s | 0.0048 s | 5.7x | 141x | 135x to 144x | yes |
+| skewed | 1,000 | 4 | 1.360 s | 0.243 s | 0.0102 s | 5.6x | 133x | 126x to 300x | yes |
+| skewed | 2,000 | 11 | 2.197 s | 0.483 s | 0.0270 s | 4.5x | 82x | 78x to 187x | yes |
+
+- C++ speedup: minimum 5.3x (cutting), maximum 246x (random, 1,000 rectangles), over 14 cases.
+- Pure-Python fixes alone: 1.7x to 7.5x.
+- All 14 outputs are identical across the three variants.
+
+Where the two speedup columns disagree (for example random 2,000: 97x from best times, 115x to 219x within the main run), the lower figure is the safer one to quote. The disagreement comes from the noise described below.
+
+## Where the time went in the original
+
+`bench/profile_original.py` (cProfile, so read the shares, not the seconds):
+
+| Function | random, 1,000 | skewed, 1,000 |
+|---|---|---|
+| `_remove_duplicates` | 93.7% | 88.2% |
+| `_select_position` | 3.6% | 7.6% |
+| `_split` | 2.4% | 3.7% |
+
+After every placement, `_remove_duplicates` compares every pair of free rectangles: 30.8 million `contains()` calls to place 1,000 rectangles in the random case, with a mean of 146.5 free rectangles per search.
+
+## Where the speedup comes from
+
+1. **Incremental duplicate removal (pure Python).** The free list never holds a rectangle that contains another once the step has run, so only pairs involving newly created pieces need checking. Measured alone: 1.0x to 7.1x (`results/phase3.json`).
+2. **Single fitness evaluation (pure Python).** The original computes each candidate's fitness twice. Together with step 1: 1.7x to 7.5x.
+3. **C++ port.** The same algorithm on plain structs instead of Python objects.
+
+## Noise on this machine
+
+- **Hybrid CPU.** The same fixed loop takes 378-414 ms on logical CPUs 0-13 and 577-1,501 ms on CPUs 14-27 (`bench/probe_cores.py`). An unrestricted process drifts between them: the first baseline showed identical runs taking 21 s and 57 s. The benchmark therefore restricts itself to CPUs 0-13.
+- **Slow phases.** Even on the fast cores, the machine drops into stretches where everything runs about 2.3x slower. Other background software was running during the first two full runs, but the third run, with it closed and the laptop on mains power, showed the same slow phases, so it is not the main cause. Thermal or power throttling is the likely explanation; I did not confirm it. Because variants are interleaved, a slow phase moves all three together: best-time speedup ratios agreed to roughly 10% between full runs, while absolute seconds did not.
+- **Consequence.** Treat the speedup ratios as the result. Treat the absolute seconds as approximate. A re-run on a desktop, or a laptop that does not throttle, would firm them up.
+
+Raw files: `results/bench.json` (main run, the third, with other software closed), `results/bench_run2.json` (second run), `results/bench_run1_single_core_pin.json` (first run, pinned to one core), `results/baseline.json` (original only), `results/phase3.json` (pure-Python steps). `results/baseline_unpinned_UNRELIABLE.json` is kept as evidence of the core-drift problem; its best times are included in the "best" columns only because lower original times make the speedup claim more conservative.

fastrectpack-0.1.0/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+All notable changes to this project are listed here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses [Semantic Versioning](https://semver.org/).
+
+## [0.1.0] - not yet released
+
+First version.
+
+### Added
+- C++17 (pybind11) implementations of `MaxRectsBl`, `MaxRectsBssf`, `MaxRectsBaf` and `MaxRectsBlsf`, exposed as subclasses of the originals. Output is identical to `rectpack` 0.2.2.
+- Fast path for plain Python `int` sizes up to 2^30. Any other input (floats, `Decimal`, numpy integers, `bool`, zero or negative sizes, larger integers) hands the object over to the original Python code for the rest of its life.
+- `fastrectpack.newPacker`, same signature as `rectpack.newPacker`, defaulting to the accelerated algorithm. Everything else `rectpack` exports is re-exported unchanged.
+- Test suite of 474 tests: step-by-step parity, edge cases, property-based tests, all 200 packer configurations that use a MaxRects algorithm.
+- Benchmarks (`bench/`), raw results (`results/`) and a chart (`docs/`).
+- CI: wheels for CPython 3.9 to 3.13 on Linux x86_64, Windows x86_64 and macOS arm64; AddressSanitizer and UndefinedBehaviorSanitizer on Linux.

fastrectpack-0.1.0/CMakeLists.txt

@@ -0,0 +1,23 @@
+cmake_minimum_required(VERSION 3.15...3.31)
+project(${SKBUILD_PROJECT_NAME} LANGUAGES CXX)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_CXX_EXTENSIONS OFF)
+
+find_package(pybind11 CONFIG REQUIRED)
+
+pybind11_add_module(_native MODULE src/fastrectpack/_native.cpp)
+
+# Optional sanitizer build for the correctness phase: pip install . -C cmake.define.FASTRECTPACK_SANITIZE=address
+set(FASTRECTPACK_SANITIZE "" CACHE STRING "Sanitizers to enable (address, undefined, thread)")
+if(FASTRECTPACK_SANITIZE)
+  if(MSVC)
+    target_compile_options(_native PRIVATE /fsanitize=${FASTRECTPACK_SANITIZE} /Zi)
+  else()
+    target_compile_options(_native PRIVATE -fsanitize=${FASTRECTPACK_SANITIZE} -fno-omit-frame-pointer -g)
+    target_link_options(_native PRIVATE -fsanitize=${FASTRECTPACK_SANITIZE})
+  endif()
+endif()
+
+install(TARGETS _native LIBRARY DESTINATION fastrectpack)

fastrectpack-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,47 @@
+# Contributing
+
+Thanks for looking. This project has one rule that matters more than the others: **fastrectpack must give exactly the same answers as the original `rectpack`.** Speed is the point, but only if the output is identical.
+
+## Set up
+
+You need Python 3.9+, CMake 3.15+ and a C++17 compiler (MSVC 2019+, GCC 9+ or Clang 10+).
+
+```
+python -m venv .venv
+. .venv/bin/activate            # Windows: .venv\Scripts\activate
+pip install ".[test]" numpy
+pytest -q
+```
+
+Re-run `pip install .` after changing `src/fastrectpack/_native.cpp`; the extension is rebuilt on install.
+
+On Windows from Git Bash, set `CMAKE_GENERATOR="Visual Studio 17 2022"` first. A "Developer PowerShell for VS" prompt should not need it, but that has not been tested.
+
+## Before you open a pull request
+
+1. **Parity first.** The tests compare every placement and the full free-rectangle list against the original, step by step. If you change behaviour on purpose, say why in the PR; if a change alters output, the tests are meant to fail.
+2. **Add a test** for what you changed. For anything touching the C++, extend `tests/test_parity.py` or `tests/test_edge_cases.py`.
+3. **Claiming a speedup?** Include numbers from `python bench/run_bench.py`, with the hardware, and say how many runs they came from. Please quote the best-of ratio and show the spread. See `BENCHMARKS.md` for why.
+4. **Style.** `ruff check .` for Python and `clang-format -i src/fastrectpack/_native.cpp` for C++. CI checks both.
+5. **Changelog.** Add a line to `CHANGELOG.md`.
+
+If a substantial part of a change was written with an AI assistant, please say so in the PR description.
+
+## Things worth knowing
+
+- Quirks inherited from rectpack are **reproduced on purpose** so that output matches (see "Behaviour inherited from rectpack" in the README). Please do not fix them here; they belong upstream.
+- The fast path only handles plain Python `int` sizes up to 2^30. Anything else falls back to the original code. Adding a float fast path is welcome, but must keep value types identical (`0` versus `0.0`), which is harder than it looks. See `docs/DESIGN.md`.
+- Moving the bin-selection loop (`PackerBBF` and friends) into C++ is the most valuable open improvement. It would lift workloads that spread rectangles over many bins above the current ~5x.
+
+## Checks you can run
+
+| What | Command |
+|---|---|
+| Tests | `pytest -q` |
+| Quick benchmark (about a minute) | `python bench/run_bench.py --quick` |
+| Mutation check (breaks the C++ on purpose, expects the tests to notice) | `python tools/mutation_check.py` |
+| AddressSanitizer + UBSan (Linux) | `bash tools/sanitize_linux.sh` |
+
+## Reporting problems
+
+Use the issue templates. For a performance report, include the workload shape (rectangle count and size range, bin size and count) and the packer settings. For anything that looks like a memory-safety problem, see [SECURITY.md](SECURITY.md) instead of opening a public issue.

fastrectpack-0.1.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "{}"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright {yyyy} {name of copyright owner}
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

fastrectpack-0.1.0/NOTICE

@@ -0,0 +1,13 @@
+fastrectpack
+Copyright 2026 Ramcharan
+
+This product is a derivative work of rectpack (https://github.com/secnot/rectpack),
+licensed under the Apache License, Version 2.0, by its author SecNot.
+
+Changes made: the MaxRects packing algorithms (MaxRectsBl, MaxRectsBssf, MaxRectsBaf,
+MaxRectsBlsf) were re-implemented in C++17 for plain Python int sizes and are exposed
+through classes that subclass the originals. All other behaviour and all other algorithms
+are the unmodified rectpack code, which is installed as a dependency and re-exported.
+
+The MaxRects family itself is described in: Jukka Jylanki, "A Thousand Ways to Pack the
+Bin - A Practical Approach to Two-Dimensional Rectangle Bin Packing" (2010).

fastrectpack-0.1.0/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: fastrectpack
+Version: 0.1.0
+Summary: Drop-in C++ accelerator for rectpack's MaxRects 2D packing algorithms, with identical output
+Keywords: rectpack,bin packing,rectangle packing,2d packing,nesting,pybind11,performance
+Author: Ramcharan
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: C++
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Project-URL: Homepage, https://github.com/p-ramcharan-dev/fastrectpack
+Project-URL: Source, https://github.com/p-ramcharan-dev/fastrectpack
+Project-URL: Issues, https://github.com/p-ramcharan-dev/fastrectpack/issues
+Project-URL: Benchmarks, https://github.com/p-ramcharan-dev/fastrectpack/blob/main/BENCHMARKS.md
+Project-URL: Original library, https://github.com/secnot/rectpack
+Requires-Python: >=3.9
+Requires-Dist: rectpack==0.2.2
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: hypothesis; extra == "test"
+Description-Content-Type: text/markdown
+
+# fastrectpack
+
+[![ci](https://github.com/p-ramcharan-dev/fastrectpack/actions/workflows/ci.yml/badge.svg)](https://github.com/p-ramcharan-dev/fastrectpack/actions/workflows/ci.yml)
+[![wheels](https://github.com/p-ramcharan-dev/fastrectpack/actions/workflows/wheels.yml/badge.svg)](https://github.com/p-ramcharan-dev/fastrectpack/actions/workflows/wheels.yml)
+![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue)
+![Python 3.9 to 3.13](https://img.shields.io/badge/python-3.9%20to%203.13-blue)
+
+A drop-in accelerator for [rectpack](https://github.com/secnot/rectpack), the pure-Python 2D rectangle packing library. The MaxRects packing algorithms are re-implemented in C++17 and produce **exactly the same packings** as the original, 5x to 246x faster depending on the workload.
+
+```python
+# before
+from rectpack import newPacker
+# after: nothing else changes
+from fastrectpack import newPacker
+```
+
+## Headline numbers
+
+Default `newPacker()` settings. Times are the best recorded run; full method and all 14 cases are in [BENCHMARKS.md](https://github.com/p-ramcharan-dev/fastrectpack/blob/main/BENCHMARKS.md).
+
+| Workload | Rectangles | Original rectpack | Pure-Python fixes only | fastrectpack (C++) | Speedup |
+|---|---|---|---|---|---|
+| random sizes | 1,000 | 3.525 s | 0.473 s | 0.0144 s | 246x |
+| random sizes | 5,000 | 21.123 s | 3.738 s | 0.1364 s | 155x |
+| few large, many small | 1,000 | 1.360 s | 0.243 s | 0.0102 s | 133x |
+| sprite sizes | 2,000 | 1.500 s | 0.322 s | 0.0177 s | 85x |
+| sheet cutting, 100 bins | 2,000 | 0.415 s | 0.214 s | 0.0780 s | 5x |
+
+Two things to read from this table:
+
+- **Part of the win needs no C++.** A better algorithm in plain Python gives 1.7x to 7.5x on its own (the "Pure-Python fixes only" column). The C++ port supplies the rest.
+- **The gain depends on the workload.** Jobs that spread rectangles over many bins gain about 5x, because the bin-selection loop is still Python. See "What is not faster" below.
+
+The benchmark machine is a laptop that drops into slow phases (probably thermal throttling), so absolute seconds vary by up to about 2.3x. Best-time speedup ratios agreed to roughly 10% between full runs.
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/p-ramcharan-dev/fastrectpack/main/docs/benchmarks-dark.png">
+    <img alt="Dumbbell chart of the speedup over the original rectpack for 14 workloads, log scale. Pure-Python fixes alone give 1.7x to 7.5x; the C++ version gives 5x to 246x, with output identical in every case. Jobs that spread rectangles over many bins gain about 5x. The same numbers are in the tables in this README and in BENCHMARKS.md." src="https://raw.githubusercontent.com/p-ramcharan-dev/fastrectpack/main/docs/benchmarks-light.png" width="760">
+  </picture>
+</p>
+
+## Install
+
+```
+pip install fastrectpack
+```
+
+Prebuilt wheels cover CPython 3.9 to 3.13 on Linux x86_64 (manylinux), Windows x86_64 and macOS arm64 (Apple silicon). Other platforms (Linux ARM, Intel Macs, Alpine/musl) and Python 3.14 are untested and build from the source distribution, which needs CMake 3.15+ and a C++17 compiler (MSVC 2019+, GCC 9+ or Clang 10+). From a checkout: `pip install .`. `rectpack==0.2.2` is installed as a dependency.
+
+## Usage
+
+Identical to rectpack:
+
+```python
+from fastrectpack import newPacker
+
+packer = newPacker()
+for width, height in [(100, 30), (40, 60), (30, 30), (70, 70), (100, 50), (30, 30)]:
+    packer.add_rect(width, height)
+packer.add_bin(300, 450)
+packer.pack()
+
+for bin_index, x, y, w, h, rid in packer.rect_list():
+    print(bin_index, x, y, w, h)
+```
+
+`fastrectpack` re-exports everything rectpack exports. `MaxRectsBl`, `MaxRectsBssf`, `MaxRectsBaf` and `MaxRectsBlsf` are replaced by accelerated subclasses of the originals; everything else is the original object.
+
+## How it works
+
+The four MaxRects classes subclass the originals and run the algorithm in a small C++17 core while every size is a plain Python `int`. Anything else falls back, for good, to the original Python code for that object.
+
+Profiling the original showed about 90% of its time in one step that compares every pair of free rectangles after each placement. The port compares only the pairs that involve newly created rectangles, which is valid because the list left by the previous step contains no rectangle that contains another. [docs/DESIGN.md](https://github.com/p-ramcharan-dev/fastrectpack/blob/main/docs/DESIGN.md) covers the design, exactly what "identical" means, and the known gaps.
+
+## What is accelerated
+
+| | Accelerated |
+|---|---|
+| MaxRects algorithms (Bl, Bssf, Baf, Blsf), with or without rotation | Yes |
+| All bin heuristics (BNF, BFF, BBF, Global), online and offline modes, all sort orders | Yes, when used with a MaxRects algorithm |
+| Sizes given as plain Python `int`, up to 2^30 | Yes |
+| Sizes given as `float`, `Decimal`, numpy integers or `bool` | No: handled by the original code, same result, original speed |
+| Skyline and Guillotine algorithms | No: unchanged original code |
+
+When an accelerated object meets an input outside the fast path, it hands its state to the original Python implementation and continues there, so results and error messages stay the same.
+
+## What is not faster
+
+- **Many-bin workloads.** With 100 open bins, most of the time goes to the Python loop that asks every bin how well a rectangle fits. That loop was left in Python, so the gain there is about 5x.
+- **Non-integer sizes.** Floats and Decimals run at the original speed.
+- **Skyline and Guillotine.** Not ported.
+
+## How correctness was checked
+
+- **Exact parity.** After every single placement, the tests compare the fitness value, the placement and the complete list of free rectangles (including its order) against the original. 474 tests, including two Hypothesis property tests (300 and 150 generated cases) and all 200 packer configurations that use a MaxRects algorithm.
+- **Edge cases.** Floats, Decimals, NaN, infinity, zero and negative sizes, booleans, strings, `None`, numpy integers, integers beyond the native range, exact fits, pieces larger than the bin. Results and exceptions match the original.
+- **Benchmark outputs.** Every benchmark run hashes the full result of all three variants; all 14 cases are identical.
+- **Sanitizers.** The suite passes under AddressSanitizer and UndefinedBehaviorSanitizer, both locally (GCC 15.2 in WSL) and on a GitHub Actions Ubuntu runner.
+- **Mutation check.** Six deliberate bugs were injected into the C++. The tests caught five; the sixth (treating edge-touching rectangles as overlapping) only adds free rectangles that the next step deletes, so the output cannot change. I reasoned that through rather than proving it formally.
+- **Platforms and Python versions.** In GitHub Actions the test suite ran inside every built wheel: Python 3.9, 3.10, 3.11, 3.12 and 3.13 on Linux x86_64, Windows x86_64 and macOS arm64. Locally it also passes on 3.13 and 3.11 on Windows.
+
+Run them yourself:
+
+```
+pip install ".[test]"
+pytest
+python bench/run_bench.py --quick     # about a minute
+python bench/run_bench.py             # full benchmark, several minutes
+```
+
+## Behaviour inherited from rectpack
+
+These were found while porting. They are reproduced on purpose, not fixed, so that results match ([`research/original_bugs.py`](https://github.com/p-ramcharan-dev/fastrectpack/blob/main/research/original_bugs.py) demonstrates each):
+
+- `validate_packing()` never compares the last rectangle with the others, so an overlap involving it goes undetected.
+- `MaxRectsBl` documents a smallest-x tie-break but takes the first candidate.
+- With the BBF bin heuristic, online `add_rect` returns `True`/`False` instead of the rectangle.
+
+## Limitations
+
+- Speed was measured on one Windows laptop only. Correctness is checked in CI on Linux, Windows and macOS (arm64), but speed on those systems has not been measured.
+- The package subclasses rectpack internals and pins `rectpack==0.2.2`. A new rectpack release would need re-checking.
+- An unpickled or deep-copied packer continues on the original Python code path: correct, but not accelerated.
+
+## Contributing and security
+
+Issues and pull requests are welcome; see [CONTRIBUTING.md](https://github.com/p-ramcharan-dev/fastrectpack/blob/main/CONTRIBUTING.md). The most useful report is a real workload where it is still slow. Please report security problems privately, as described in [SECURITY.md](https://github.com/p-ramcharan-dev/fastrectpack/blob/main/SECURITY.md).
+
+## Credits and licence
+
+Apache-2.0, the same licence as rectpack, of which this is a derivative work. rectpack is by SecNot. The MaxRects algorithms come from Jukka Jylänki, "A Thousand Ways to Pack the Bin" (2010). See [NOTICE](https://github.com/p-ramcharan-dev/fastrectpack/blob/main/NOTICE).