MaxRectsPacker

When instantiating new MaxRectsPacker(maxWidth, maxHeight, padding, options), you can provide an options object to control packing behavior:

• smart: (boolean, default true) Packs with the smallest possible size.
• pot: (boolean, default true) Rounds bin size up to the smallest power of 2.
• square: (boolean, default false) Forces bin sizes to always be square.
• allowRotation: (boolean, default false) Allows 90-degree rotation of rectangles to improve packing efficiency.
• tag: (boolean, default false) Enables tag-based group packing.
• exclusiveTag: (boolean, default true) If false, the packer tries to put tagged rectangles into the same bin. If true, tagged rects will have dependent bins.
• border: (number, default 0) Sets the atlas edge spacing.
• logic: (number, default 1) Determines how free spaces are selected:
  • 0: MAX_AREA (selects free space with smallest loss of area).
  • 1: MAX_EDGE (selects free space with smallest loss of width or height).
  • 2: FILL_WIDTH (fills complete width first before next row).

To use MaxRectsPacker, import the class, initialize it with bin constraints and options, and then add rectangles using addArray or add.

Important Migration Notes:

• Since v2.0.0, use import { MaxRectsPacker } from 'maxrects-packer' or require('maxrects-packer').MaxRectsPacker.
• Since v2.1.0, you can pass any object with width and height properties (no need for a specific schema).
• The Rectangle constructor order is (width, height, x, y, rotated).

let MaxRectsPacker = require("maxrects-packer").MaxRectsPacker;
const options = {
    smart: true,
    pot: true,
    square: false,
    allowRotation: true,
    tag: false,
    border: 5
};

// width, height, padding, options
let packer = new MaxRectsPacker(1024, 1024, 2, options);

let input = [
    {width: 600, height: 20, name: "tree"},
    {width: 600, height: 20, name: "flower"},
    {width: 1000, height: 1000, name: "background"}
];

packer.addArray(input);

// Access the resulting bins
packer.bins.forEach(bin => {
    console.log(bin.rects);
});

The MaxRectsPacker class provides the following methods for managing the packing process:

• new MaxRectsPacker(maxWidth, maxHeight, [padding, options]): Creates a new packer instance. maxWidth and maxHeight are applied to all bins.
• add(width, height, data) or add({width, height, ...}): Adds a single rectangle. data can be any object and will be stored with the rectangle's position.
• addArray(rects[]): Adds multiple rectangles at once. This is more efficient than multiple add() calls because input is automatically sorted.
• next(): Stops adding elements to the current bin and starts a new bin. Subsequent elements will not be added to previous bins.
• repack(quick = true): Repacks elements. If quick is true, only dirty bins are repacked. If false, all rects are re-sorted and repacked for higher efficiency (slower).
• save(): Returns an array of objects representing current bin settings and free areas. Useful for persisting state via JSON.stringify().
• load(bins): Restores settings from a previously saved array (e.g., from JSON.parse()). Allows continuing packing without overlapping previous areas.

Properties:

• bins: An array of bin objects. Each bin has width, height, and a rects array.
• bins[n].rects: An array of rectangle objects. Each rect contains x, y, width, height, rot, data, and an optional oversized flag (set to true if the rect exceeds maxWidth or maxHeight).

The MaxRectsBin constructor accepts an IOption object to control packing behavior.

The IOption interface defines the configuration for the MaxRect Packer. You can use these properties to control sizing behavior, rotation, grouping, and spacing.

Available Options

const options: IOption = {
  smart: true,
  pot: true,
  allowRotation: false,
  border: 2,
  logic: PACKING_LOGIC.MAX_AREA
};

The Rectangle class provides static and instance methods to perform geometric tests:

• collide(rect: IRectangle): Returns true if this rectangle overlaps with the provided rectangle.
• Rectangle.Collide(first: IRectangle, second: IRectangle): Static method to test collision between two rectangles.
• contain(rect: IRectangle): Returns true if this rectangle completely encloses the provided rectangle.
• Rectangle.Contain(first: IRectangle, second: IRectangle): Static method to test if the first rectangle contains the second.

import { Rectangle, IRectangle } from 'maxrects-packer';

const rect1: IRectangle = { x: 0, y: 0, width: 10, height: 10 };
const rect2: IRectangle = { x: 5, y: 5, width: 10, height: 10 };

// Instance method
const isColliding = new Rectangle(0,0).collide(rect1); // Note: logic depends on instance state

// Static methods
const collision = Rectangle.Collide(rect1, rect2);
const containment = Rectangle.Contain(rect1, rect2);