{"id":13492299,"url":"https://github.com/soimy/maxrects-packer","last_synced_at":"2025-12-14T21:32:28.572Z","repository":{"id":23886773,"uuid":"100093943","full_name":"soimy/maxrects-packer","owner":"soimy","description":"A max rectangle 2d bin packer npm-module for packing glyphs or images into multiple sprite-sheet/atlas","archived":false,"fork":false,"pushed_at":"2023-03-13T11:07:28.000Z","size":1787,"stargazers_count":176,"open_issues_count":9,"forks_count":32,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-04-01T08:20:22.528Z","etag":null,"topics":["atlas","max-rectangle-algorithm","maxrects","nodejs","npm-module","packer","packing-algorithm","packing-glyphs","sprites","spritesheet","spritesheet-packing-algorithm"],"latest_commit_sha":null,"homepage":"https://soimy.github.io/maxrects-packer/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/soimy.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2017-08-12T06:28:09.000Z","updated_at":"2024-03-29T08:13:54.000Z","dependencies_parsed_at":"2023-01-14T13:24:25.056Z","dependency_job_id":"b52ec7e1-c5d7-428d-905e-8cdc9ce0900f","html_url":"https://github.com/soimy/maxrects-packer","commit_stats":{"total_commits":109,"total_committers":3,"mean_commits":"36.333333333333336","dds":0.04587155963302747,"last_synced_commit":"11fd72cdefa3dc56ce569f8ca873ca8cc2be81e0"},"previous_names":[],"tags_count":27,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soimy%2Fmaxrects-packer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soimy%2Fmaxrects-packer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soimy%2Fmaxrects-packer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soimy%2Fmaxrects-packer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/soimy","download_url":"https://codeload.github.com/soimy/maxrects-packer/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246004463,"owners_count":20708223,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["atlas","max-rectangle-algorithm","maxrects","nodejs","npm-module","packer","packing-algorithm","packing-glyphs","sprites","spritesheet","spritesheet-packing-algorithm"],"created_at":"2024-07-31T19:01:04.807Z","updated_at":"2025-12-14T21:32:28.564Z","avatar_url":"https://github.com/soimy.png","language":"JavaScript","readme":"# ![icon](./assets/favicon32.png) Max Rects Packer\n\n[![Node.js CI](https://github.com/soimy/maxrects-packer/actions/workflows/node.js.yml/badge.svg)](https://github.com/soimy/maxrects-packer/actions/workflows/node.js.yml)\n[![codecov](https://codecov.io/gh/soimy/maxrects-packer/branch/master/graph/badge.svg)](https://codecov.io/gh/soimy/maxrects-packer)\n[![npm version](https://badge.fury.io/js/maxrects-packer.svg)](https://badge.fury.io/js/maxrects-packer)\n![npm](https://img.shields.io/npm/dm/maxrects-packer.svg)\n![NPM Type Definitions](https://img.shields.io/npm/types/maxrects-packer)\n\nA simple max rectangle 2d bin packing algorithm for packing glyphs or images into multiple sprite-sheet/atlas. Minimalist with no module dependency.\n\nThis is a evolved version of [Multi-Bin-Packer](https://github.com/marekventur/multi-bin-packer) with much efficient packing algorithm. All interfaces and methods are inherited so no tweaks needed in your current code except module name.\n\nIt differs from the long list of similar packages by its packing approach: Instead of creating one output bin with a minimum size this package is trying to create a minimum number of bins under a certain size. This avoids problems with single massive image files that are not browser-friendly. This can be especially useful for WebGL games where the GPU will benefit from spritesheets close to power-of-2 sizes.\n\nAnd you can also save/load to reuse packer to add new sprites. (Below is a demo atlas packed with two difference bitmap fonts)\n\n![Preview image](./assets/preview.png)\n\n## [Changelog](https://github.com/soimy/maxrects-packer/blob/master/CHANGELOG.md)\n\n## Installing\n\n```bash\nnpm install maxrects-packer --save\n```\n\n## Usage\n\n**Note:** *Since version 2.0.0 Max Rects Packer is rewritten in `typescript` and change the import method from old `require(\"maxrects-packer\")` to `require(\"maxrects-packer\").MaxRectsPacker` or more fashioned `import` statement.*\n\n**Note:** *Since version 2.1.0 packer can be fed with any object with `width \u0026 height` members, no need to follow `{ width: number, height: number, data: any }` pattern, if you are using `typescript`, that also mean any class extending `MaxRectsPacker.IRectangle`*\n\n**Note:** *Since version 2.1.0 Rectangle class constructor API is changed from `new Rectangle(x, y, width, height, rotated)` to `new Rectangle(width, height, x, y, rotated)`, cos most cases you only need to feed w/h and omit the rest like `new Rectangle(100, 100)` and left `x,y,rotated` to default value.\n\n```javascript\nlet MaxRectsPacker = require(\"maxrects-packer\").MaxRectsPacker;\nconst options = {\n    smart: true,\n    pot: true,\n    square: false,\n    allowRotation: true,\n    tag: false,\n    border: 5\n}; // Set packing options\nlet packer = new MaxRectsPacker(1024, 1024, 2, options); // width, height, padding, options\n\nlet input = [ // any object with width \u0026 height is OK since v2.1.0\n    {width: 600, height: 20, name: \"tree\", foo: \"bar\"},\n    {width: 600, height: 20, name: \"flower\"},\n    {width: 2000, height: 2000, name: \"oversized background\", {frameWidth: 500, frameHeight: 500}},\n    {width: 1000, height: 1000, name: \"background\", color: 0x000000ff},\n    {width: 1000, height: 1000, name: \"overlay\", allowRotation: true}\n];\n\npacker.addArray(input); // Start packing with input array\npacker.next(); // Start a new packer bin\npacker.addArray(input.slice(2)); // Adding to the new bin\npacker.bins.forEach(bin =\u003e {\n    console.log(bin.rects);\n});\n\n// Reuse packer\nlet bins = packer.save();\npacker.load(bins);\npacker.addArray(input);\n\n```\n\n## Test\n\n```bash\nnpm test\n```\n\n## API\n\nNote: maxrects-packer requires node \u003e= 4.0.0\n\n#### ```new MaxRectsPacker(maxWidth, maxHeight[, padding, options])```\n\nCreates a new Packer. maxWidth and maxHeight are passed on to all bins. If ```padding``` is supplied all rects will be kept at least ```padding``` pixels apart.\n\n- `options.smart` packing with smallest possible size. (default is `true`)\n- `options.pot` bin size round up to smallest power of 2. (default is `true`)\n- `options.square` bin size shall alway be square. (default is `false`)\n- `options.allowRotation` allow 90-degree rotation while packing. (default is `false`)\n- `options.tag` allow tag based group packing. (default is `false`)\n- `options.exclusiveTag` tagged rects will have dependent bin, if set to `false`, packer will try to put tag rects into the same bin (default is `true`)\n- `options.border` atlas edge spacing (default is 0)\n- `options.logic` how to fill the rects. There are three options: 0 (max area),  1 (max edge), 2 (fillWidth). Default is 1 (max edge)\n\n#### ```packer.add(width, height, data)``` +1 overload\n\nAdds a rect to an existing bin or creates a new one to accommodate it. ```data``` can be anything, it will be stored along with the position data of each rect.\n\n#### ```packer.add({width: number, height: number, ... })``` +1 overload\n\nAdds a rect to an existing bin or creates a new one to accommodate it. Accept any object with `width \u0026 height`. If you are using `typescript`, that means any class extends `MaxRectsPacker.IRectangle`\n\n#### ```packer.addArray([{width: number, height: number, ...}, ...])```\n\nAdds multiple rects. Since the input is automatically sorted before adding this approach usually leads to fewer bins created than separate calls to ```.add()```\n\n#### ```packer.repack(quick: boolean = true)```\n\nRepack all elements inside bins. If `quick == true`, only bins with `dirty` flag will be repacked. If `false` is passed, all rects inside this packer will be re-sort and repacked, might result different bin number. Slower but high packing efficiency.\n\n#### ```packer.next()```\n\nStop adding new element to the current bin and return a new bin. After calling `next()` all elements will no longer added to previous bins.\n\n#### ```let bins = packer.save()```\n\nSave current bins settings and free area to an Array of objects for later use. Better to `JSON.stringify(bins)` and store in file.\n\n#### ```packer.load(bins)```\n\nRestore previous saved `let bins = JSON.parse(fs.readFileSync(savedFile, 'utf8'));` settings and overwrite current one. Continue packing and previous packed area will not be overlapped.\n\n#### ```packer.bins```\n\nArray of bins. Every bin has a ```width``` and ```height``` parameter as well as an array ```rects```.\n\n#### ```packer.bins[n].rects```\n\nArray of rects for a specific bin. Every rect has ```x```, ```y```, ```width```, ```height```, ```rot``` and ```data```. In case of an rect exceeding ```maxWidth```/```maxHeight``` there will also be an ```oversized``` flag set to ```true```.\n\n## Support for 90-degree rotation packing\n\nIf `options.allowRotation` is set to `true`, packer will attempt to do an extra test in `findNode()` on rotated `Rectangle`. If the rotated one gives the best score, the given `Rectangle` will be rotated in the `Rectangle.rot` set to `true`.\n\n## Support for tag based group packing\n\nIf `options.tag` is set to `true`, packer will check if the input object has `tag: string` property, all input with same `tag` will be packed in the same bin.\n\n## Support for oversized rectangles\n\nNormally all bins are of equal size or smaller than ```maxWidth```/```maxHeight```. If a rect is added that individually does not fit into those constraints a special bin will be created. This bin will only contain a single rect with a special \"oversized\" flag. This can be handled further on in the chain by displaying an error/warning or by simply ignoring it.\n\n## Packing logic\n\n`options.logic` allows to change the method on how the algorithm selects the free spaces. There are three options:\n\n`{option.logic = 0}` Logic is MAX_AREA, selects the free space with the smallest loss of area.\n\n`{option.logic = 1}` Logic is MAX_EDGE, is default and selects the free space with the smallest loss of either width or height.\n\n`{option.logic = 2}` Logic is FILL_WIDTH, fills the complete width first before placing elements in next row. To get the used height `bin.height` only gives correct values with options: `{pot: false, square: false}`. Best results also with `option.allowRotation = true`\n\n\n\n## Packing algorithm\n\nUse Max Rectangle Algorithm for packing, same as famous **Texture Packer**\n","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoimy%2Fmaxrects-packer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsoimy%2Fmaxrects-packer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoimy%2Fmaxrects-packer/lists"}