RectangleBinPack.CSharp 1.0.4

RectangleBinPack C#

中文文档 (Chinese)

A complete, high-performance C# port of the famous RectangleBinPack library by Jukka Jylänki.

🆕 New Feature: Added SingleBinPack algorithm specifically optimized for packing large quantities of a single type of rectangle.

📦 Algorithms Included

This library faithfully implements the core algorithms from the original C++ library, plus a new specialized algorithm:

1. MaxRects (MaxRectsBinPack) - Recommended. Highest packing density for mixed shapes.
2. Skyline (SkylineBinPack) - Fastest. Good for runtime packing.
3. Guillotine (GuillotineBinPack) - Simulates edge-to-edge cuts.
4. Shelf (ShelfBinPack) - Simple row-based layout.
5. SingleBin (SingleBinPack) - [New] Optimized for mass production of a single part type. Supports mixed horizontal/vertical layouts.

🌟 Single Part Packing Examples

The new SingleBinPack algorithm is designed to maximize utilization when packing thousands of identical items. It automatically determines the best combination of horizontal and vertical placements. | | | | |

⚙️ Algorithm Parameters & Heuristics

Different algorithms offer various heuristic strategies. Choosing the right heuristic significantly impacts the packing quality.

1. MaxRectsBinPack

Init: new MaxRectsBinPack(width, height, allowRotations: true) Method: Insert(w, h, FreeRectChoiceHeuristic)

2. SkylineBinPack

Init: new SkylineBinPack(width, height, useWasteMap: true) Method: Insert(w, h, LevelChoiceHeuristic)

3. GuillotineBinPack

Init: new GuillotineBinPack(width, height) Method: Insert(w, h, merge, FreeRectChoiceHeuristic, GuillotineSplitHeuristic) Requires two strategies: one for choosing the rect, one for splitting the space.

A. Choice Strategy (FreeRectChoiceHeuristic):

• RectBestAreaFit: Preferred.
• RectBestShortSideFit / RectBestLongSideFit
• (And corresponding "Worst" fits)

B. Split Strategy (GuillotineSplitHeuristic):

• SplitMinimizeArea: Recommended. Splits so the smaller leftover rectangle is minimized (keeping the larger area intact).
• SplitMaximizeArea: Splits so the larger leftover rectangle is maximized.
• SplitShorterLeftoverAxis / SplitLongerLeftoverAxis.

4. ShelfBinPack

Init: new ShelfBinPack(width, height, useWasteMap: false) Method: Insert(w, h, ShelfChoiceHeuristic)

🚀 Installation

This library is available on NuGet.

.NET CLI

dotnet add package RectangleBinPack.CSharp

Package Manager

Install-Package RectangleBinPack.CSharp

💻 Usage

1. Basic Example (MaxRects - Mixed Parts)

using System;
using System.Collections.Generic;
using RectangleBinPacking;

public class Program
{
    public static void Main()
    {
        // 1. Initialize a 1024x1024 bin, allowing 90-degree rotations
        var packer = new MaxRectsBinPack(1024, 1024, allowRotations: true);

        // 2. Prepare items to pack
        var items = new List<(int w, int h)> 
        { 
            (200, 100), (50, 50), (300, 300), (1000, 500) 
        };

        // 3. Pack items
        foreach (var item in items)
        {
            Rect result = packer.Insert(item.w, item.h, FreeRectChoiceHeuristic.RectBestShortSideFit);

            if (result.Height > 0)
            {
                Console.WriteLine($"Packed {item.w}x{item.h} at X={result.X}, Y={result.Y}, Rotated={result.Width != item.w}");
            }
            else
            {
                Console.WriteLine($"Failed to pack {item.w}x{item.h}: Bin is full!");
            }
        }
    }
}

2. Single Part Example (SingleBinPack)

using RectangleBinPacking;

// 1. Initialize bin size (Width, Height)
var singlePacker = new SingleBinPack(3000, 1500);

// 2. Pack 500 copies of a 200x100 part
// The algorithm will automatically decide the optimal mix of horizontal and vertical placements.
List<Rect> results = singlePacker.Insert(partWidth: 200, partHeight: 100, quantity: 500);

Console.WriteLine($"Successfully packed {results.Count} items.");
foreach(var rect in results)
{
    Console.WriteLine($"Part at: {rect.X}, {rect.Y} Size: {rect.Width}x{rect.Height}");
}

3. Advanced Example (Skyline with Waste Map)

// Initialize Skyline packer, enable WasteMap (second arg true) to recover gaps
var skylinePacker = new SkylineBinPack(2048, 2048, useWasteMap: true);

Rect node = skylinePacker.Insert(200, 150, SkylineBinPack.LevelChoiceHeuristic.LevelBottomLeft);

if (node.Height > 0)
{
    Console.WriteLine($"Skyline Placed at: {node.X}, {node.Y}");
}

📄 License

Released under Public Domain (Unlicense) or MIT. You are free to use, modify, and distribute this software for any purpose, commercial or otherwise.