Arrange Master Documentation

Current Version: 1.3.1

1. Installation
2. Upgrading & Complete Uninstallation
3. Introduction
4. The Main Interface
5. Preparing Items for Arrangement
6. The Arrangement Workflow: Understanding Sessions
7. Layout Methods
   • Grid Layout
   • Knolling Layout
   • Greedy Layout
   • Shape Respect Layout
   • Dense Packing (True-Shape Nesting)
8. Overflow Placement
9. Common Features & Best Practices
10. Prepress Splitter Script
11. Changelog

1. Installation

Windows Installer (Recommended)

For Windows users, the easiest and most reliable way to install Arrange Master is by using the provided installer.

1. Unzip the archive you downloaded after purchase.
2. Open the folder named Windows Install.
3. Run the ArrangeMaster-v1.x.x-Setup.exe file.
4. Follow the on-screen instructions. The installation is fully automatic and performs necessary registry configurations for the user.

ZXP Installers (macOS & Advanced Windows)

To install the ArrangeMaster.zxp file manually, you need a dedicated extension manager application.

Option 1: Anastasiy’s Extension Manager (Recommended)

This is the most popular and reliable tool for managing Adobe extensions.

1. Download and install Anastasiy’s Extension Manager from: install.anastasiy.com
2. Launch the Extension Manager.
3. Simply drag and drop your ArrangeMaster.zxp file onto the Extension Manager window.
4. The installation will complete automatically.

Option 2: ZXPInstaller

A great alternative if you encounter any issues with the first option.

1. Download and install ZXPInstaller from: zxpinstaller.com
2. Launch ZXPInstaller.
3. Drag and drop your ArrangeMaster.zxp file onto its window to install.

Option 3: aescripts + aeplugins Manager App

If the other installers cannot detect your Adobe applications for any reason, the aescripts manager is a powerful alternative that often succeeds.

1. Download and install the manager app from: aescripts.com/learn/aescripts-aeplugins-manager-app/
2. Launch the app and log in or create an account.
3. In the top menu, go to File > Install ZXP.
4. Select your ArrangeMaster.zxp file to install it.

Finding the Panel in Illustrator

After the installation is complete, you must restart Adobe Illustrator.
Once restarted, you can find the panel in the main menu under:
Window > Extensions > Arrange Master

2. Upgrading & Complete Uninstallation

When installing a new major version of Arrange Master, it is strictly recommended to completely remove the old version first to prevent file conflicts within the Adobe CEP engine.

For Windows Installer Users:

1. Open Windows Settings > Apps > Installed apps.
2. Find "Arrange Master", click the menu, and select Uninstall.
3. Alternatively, navigate to your Start Menu, find the Arrange Master folder, and run the uninstaller.

For ZXP Manager Users (macOS & Windows):

Open Anastasiy’s Extension Manager or aeplugins Manager App, select Arrange Master from the list of Illustrator extensions, and click the Remove button. ZXPInstaller does not have an automatic uninstall feature, so you will have to manually check all possible CEP extension locations.

Manual Deletion (If all else fails):

If the plugin panel persists or the installer throws an error, you must manually delete the extension folder. Close Adobe Illustrator and delete the com.andrewrybalko.arrangemaster folder located in the following directories:

• Windows:
  C:\Users\YOUR_USERNAME\AppData\Roaming\Adobe\CEP\extensions\
C:\Program Files (x86)\Common Files\Adobe\CEP\extensions\
• macOS:
  ~/Library/Application Support/Adobe/CEP/extensions/
/Library/Application Support/Adobe/CEP/extensions/

3. Introduction

Welcome to Arrange Master! This guide will walk you through all the features of the plugin to help you transform chaotic object sets into structured compositions.

Core Principles:

• The Container: The largest object in your selection is automatically treated as the container.
• The Items: All other selected objects are treated as items to be arranged inside the container.
• Non-Destructive Environment: Arrange Master operates entirely within a strict Session-Based Workflow. Original objects are hidden and preserved, while algorithmic operations are performed only on generated duplicates.

4. The Main Interface

The interface is modular, exposing settings only relevant to the currently selected layout method. The active panel is indicated by distinct color themes.

1. Method Icons: At the top of the panel, you will find four icons. Each icon represents a different arrangement algorithm. Clicking an icon selects that method and reveals its specific settings below.
2. Dynamic Settings Area: This central part of the panel changes based on the selected method, showing only the relevant controls for your current task.
3. Action Buttons & Status Bar: The bottom section contains the main control buttons (Arrange, Randomize, Ok, Cancel) and a status bar that provides progress feedback.

5. Preparing Items for Arrangement

The efficiency of the layout depends on how your artwork is structured before initialization.

Preparation for Standard Methods

Standard algorithms calculate placement based exclusively on the Bounding Boxes (rectangular perimeter) of the items.

• Gaps: If an object has a complex shape with internal empty space (e.g., an "L" shaped lamp post), the standard algorithm treats that empty space as solid matter.
• Optimization: To achieve higher density in standard modes, manually group sub-elements into solid rectangular blocks before arranging them.

Preparation for Dense Packing (True-Shape Nesting)

Dense Packing bypasses bounding boxes and analyzes the True Vector Geometry of the object.

• Vector Only: Dense Packing strictly requires mathematical path data. Raster images are NOT supported in this mode. If you attempt to use Raster items with Dense Packing enabled, the plugin will throw an error or skip them.

Supported Object Types

Arrange Master processes standard Illustrator objects including Paths, Compound Paths, Groups, Text Objects, Symbols, and Raster Images (Embedded or Linked). The plugin accurately measures visible bounds, correctly parsing complex clipping masks and scaled symbols.

Multi-Layer Retention (Prepress Workflow)

Arrange Master supports arranging complex multi-layer designs (such as files divided into CUT, PRINT, MARKS, etc.) without flattening your layer hierarchy:

• Auto-Clustering: The plugin automatically identifies overlapping objects across different layers. It groups them mathematically during the session so they are moved and rotated as a single, cohesive unit.
• Layer Restoration: When you finalize the layout (clicking Ok) or cancel the session, Arrange Master automatically unpacks the clusters and distributes each child object back to its originating layer while maintaining relative stacking order.

6. The Arrangement Workflow: Understanding Sessions

Arrange Master uses a Session-Based Workflow to protect your original objects and maintain stability during complex calculations.

Starting a Session:

A session begins the very first time you click the Arrange button after making a selection.

1. It securely hides your original selected items on their native layer.
2. It creates temporary working copies of your items to perform all mathematical operations.

Working within a Session:

Once active, you can experiment freely:

• Clicking Arrange again will recalculate the layout with new settings instantly.
• Clicking Randomize will apply the same settings but shuffle the item placement order.

Note: Switching to a different Illustrator document will force the plugin to auto-terminate the session to prevent data corruption.

7. Layout Methods

Grid Layout

This method arranges items in a structured, uniform grid based on their bounding boxes. It is used for organizing icon sets or generating patterns.

Standard Settings:

• Rows & Columns: Defines the dimensions of the grid.
• Vary Rotation: Adds randomness by rotating each item (e.g., 90° rotates between -90° and +90°).
• Vary Size: Randomly scales each item. A value of x2 scales between x1 and x2.
• Offset Odd/Even Rows: Creates a staggered, "checkerboard" pattern.
• Size Limit OFF: By default, items larger than a grid cell are considered "overflow". Check this to force large items into the grid, centering them in their respective cells.

Special Mode: Single Item Fill

When the Single Item Fill checkbox is enabled, the panel switches to a specialized mode. Instead of arranging a selection of different objects, it calculates the maximum capacity and fills the container with copies of one selected item.

• Min. Spacing: Sets the distance between duplicated items. Decimal values (e.g., 0.5) are supported.
• Allow 90° turn: Allows the item to be rotated orthogonally to maximize capacity.

Knolling Layout

Based on the "Maximal Empty Rectangles" algorithm, this method packs bounding boxes efficiently. It places large items first, then executes a second pass to fill remaining cavities with smaller details.

Settings:

• Fill Direction: Sets the primary horizontal packing flow (Left-to-Right or Right-to-Left).
• Min. Spacing: The minimum distance guaranteed between items.
• Fit to Container: Automatically solves a quadratic equation to scale your items proportionally so they exactly fill the container's usable area.
• Efficiency Factor: (Active when "Fit to Container" is ON). Determines how tight the scaling calculation should be (0.75 - 1.00).
• Outer Padding OFF: Disables padding between items and the container's edge.
• Allow 90° turn: Allows orthogonal rotation for a better fit.

Greedy Layout

A high-speed packing method that places items into the first available position based on their bounding box perimeters.

Settings:

• Fill Direction: Sets the vertical packing priority (Top-Down or Bottom-Up).
• Min. Spacing: Distance between items.
• Outer Padding OFF: Disables container edge padding.
• Allow 90° turn: Orthogonal rotation support.

Shape Respect Layout

This layout operates inside custom vector shapes, such as text outlines, angled polygons, or containers with internal holes.

Settings:

• Fill Direction: Top-Down or Bottom-Up placement priority.
• Min. Spacing: Gap distance.
• Allow 90° turn: Tests horizontal and vertical orientation.
• Free Rotation: Applies a random 360° rotation to items prior to packing.
• Outer Padding OFF: Disables edge margins.
• Chaotic Mode: Uses a random placement coordinate algorithm instead of an ordered grid, generating natural, organic dispersion patterns.

Dense Packing (True-Shape Nesting)

Available as a checkbox in both Greedy Layout and Shape Respect Layout, this activates Arrange Master's flagship feature: the Chromium Math Engine. This transitions the plugin from a simple bounding box arranger into a professional True-Shape Nesting tool.

Dense Packing relies on deep Vector Path Analysis. Instead of drawing a box around an item, the engine calculates the exact mathematical contour. This allows items to interlock, filling concavities and isolated cavities, providing high-yield material optimization for print production, CNC, and laser cutting preparation.

How it works:

• In Greedy Layout: Evaluates exact shapes and packs them tightly inside a standard rectangular container.
• In Shape Respect Layout: Rasterizes custom vector containers (including internal holes) and performs exact shape nesting within those specific boundaries.

Dense Packing Settings:

• Analysis Precision: Controls the scanning step of the engine (range 1 to 50, default is 5). The internal grid operates at a strict 1pt resolution for exact padding, but this slider determines how fast the algorithm searches. Lower values yield tighter interlocks. Higher values increase calculation speed for massive object counts.
• Free Rotation: (Replaces "Allow 90° turn"). The Chromium engine evaluates 24 different angles (15° steps) for every vector path to find the absolute maximum density fit.
• Align Final Edge: Post-processes the layout by aligning the final ragged boundary for a cleaner finish.

Smart Mode vs. Fast Mode: If you select fewer than 50 objects, the engine automatically switches to a Smart Euclidean Mode. Rather than placing an object in the first available slot, it analyzes all possible coordinates to minimize the total radial footprint, ensuring identical asymmetrical parts interlock perfectly. For over 50 objects, it uses a high-speed lexicographical line-packing algorithm.

8. Overflow Placement: Handling Unplaced Items

If an item cannot fit inside the container, it is processed as an "overflow" item.

Overflow items are placed in a structured block directly above the container. They are arranged according to these rules:

• They are sorted by height, from tallest to shortest.
• They wrap to a new row once they reach the width of the main container, preventing infinite horizontal lines.
• A consistent spacing is maintained vertically and horizontally.

To fit remaining items, increase the container size, lower the "Min. Spacing", or activate Dense Packing, then click Arrange again.

9. Common Features & Best Practices

• Automatic Container Detection: You don't need to manually assign the container. The plugin automatically identifies the object with the largest area in your selection to act as the boundary.
• Automatic Z-Order: The container is automatically sent to the back of the layer stack, ensuring all arranged items remain visible on top.
• Freedom during a Session: While a session is active, your Illustrator document remains fully interactive. You can:
  • Deselect everything to get an unobstructed view of the layout.
  • Zoom and pan around your artboard to inspect details.
  • Manually resize or recolor the container object. After making changes, simply click Arrange again to immediately recalculate the layout within the updated parameters.
• Smart Caching for Dense Packing: The Chromium Engine stores the complex mathematical geometry of your vector paths in local memory. After the initial Arrange execution, subsequent adjustments—such as changing the "Min. Spacing" or altering the "Analysis Precision" step—are processed almost instantly without re-reading the Illustrator DOM. Note: The cache only triggers a rebuild if you modify structural rotation rules (like toggling "Free Rotation") or begin a completely new session.

• Iterative Container Tuning: You can treat the container as a live bounding box. Feel free to shrink or expand your container object from the bottom or right edges to physically refine your composition's density. If you make the container tighter, the plugin will intelligently push excess objects out into the Overflow block on the next Arrange click. Simply expand the container slightly to reclaim those items back into the main layout.

10. Prepress Splitter Script

The Prepress Splitter.jsx is a specialized script designed to bridge the gap between automated nesting and wide-format printing production. It distributes nested components into dedicated layers based on object type and Z-order.

Layer Distribution Logic

• CUT Layer: Identifies the primary vector clipping mask of each group and duplicates it as a non-clipping path with a 100% Magenta (E6007E) 1pt stroke. Deep mask cleaning ensures Compound Paths are styled correctly.
• PRINT Layer: Collects the base (bottom-most) raster image. Note: If a sticker is purely vector-based with no rasters, the script executes a Vector-Only Merge (Live Pathfinder Add) to generate the CUT contour, and sends the original vectors to this PRINT layer.
• QR Layer (PRINT 2): Collects all raster elements stacked above the base image, supporting multiple QR codes, spot varnishes, or floating rasters.
• MARKS Layer: Collects auxiliary vector elements that are not clipping masks.

How to Use

1. Group your design (raster/vector), cut line (clipping mask), and marks into individual sticker groups.
2. Nest the groups using Arrange Master and click Ok.
3. Select the nested groups, go to File > Scripts > Other Script..., and run Prepress-Splitter.jsx.
4. Select the required layers. Check "Keep Clipping Masks" to preserve strict mask boundaries on raster print files.

11. Changelog

Version 1.3.1 (May 27, 2026)

Maintenance improving prepress automation.

• Multi-Layer Retention: Added full native support for preserving layer structures (e.g., CUT, PRINT, QR layers) during and after arrangement across all algorithms.

Version 1.3.0 (May 10, 2026)

Major architectural update focusing on performance and precision.

• Shape Respect True-Shape Support: Dense packing is now natively supported within custom non-rectangular containers, perfectly wrapping around isolated internal cavities and holes.
• Chromium Engine Offloading: Shape Respect (Accurate Mode) and Dense Packing mathematics are now fully processed in the Chromium Engine, increasing speed exponentially for complex documents.
• True-Shape Nesting Upgrade: Replaced bounding box optimization with a Smart Euclidean Bin Packing system for small batches (<50 items), achieving mathematically perfect interlocking geometry.
• UI Enhancement: Introduced dynamic theme color coding linked to active layout panels.

Version 1.2.4 (April 20, 2026)

Maintenance update.

• Overflow Wrapping. Overflow items no longer form a single infinite line that exceeds Illustrator's canvas limits. They now wrap to new rows (forming a compact block) based on the container's width, making it much easier to select and manage unplaced items.
• Advanced Silhouette Recognition. Speed boost for complex vector groups (e.g., Image Trace results). Dense Packing now automatically filters out thousands of internal micro-paths and "enclosed" details to focus strictly on the object's outer contour, preventing long freezes and crashes.

Version 1.2.3 (April 17, 2026)

Maintenance performance and precision update.

• Architecture Upgrade: Chromium Math Engine. Dense Packing calculations have been moved to the high-performance background engine. This provides a massive speed boost, especially when arranging hundreds of objects.
• Improved Clipping & Compound Mask Support. Resolved coordinate shifts in complex masks and fixed issues where hidden content affected the layout density of Compound Path masks.
• Target Layer Protection. Fixed the "Target layer cannot be modified" error. Temporary groups are now strictly created on the layer containing your selection, even if other layers are locked or hidden.
• Global Input Support. All numeric fields now support both dot (.) and comma (,) as decimal separators for better international usability.

Version 1.2.2 (March 31, 2026)

Maintenance update.

• Dense Packing Optimization. Improved packing density and more accurate response to "Min. Spacing" settings.

Version 1.2.1 (March 19, 2026)

Maintenance update.

• Universal Clipping Mask Support. All arrangement methods (Grid, Knolling, Greedy and Shape Respect) now correctly process objects with Clipping Masks. The engine no longer considers hidden elements outside the mask area, focusing strictly on the mask's true bounding box.

Version 1.2.0 (March 1, 2026)

Major update transforming the plugin into an industrial-grade nesting engine, featuring entirely new mathematics, real-time UI feedback, and intelligent scaling.

• New Feature: Visual Progress Bar. The Status Bar now features a smooth, animated background progress filler. Long operations like Dense Packing now provide clear visual feedback that the engine is working.
• New Feature: Intelligent Auto-Resizing ("Fit to Container"). Knolling Layout now includes a powerful math engine that solves a quadratic equation to perfectly scale your items up or down to fill 100% of the container's usable area, automatically accounting for Min. Spacing. Includes a dynamic "Efficiency Factor" stepper (0.75 - 1.00) for tight control over the scaling aggressiveness.
• New Feature: Free Rotation (360°). Dense Packing now supports true arbitrary rotation. The algorithm evaluates 24 different angles (15° steps) for every single item to achieve maximum density. It uses "Rational Fallback" logic: items stay orthogonally straight by default, and only tilt if it mathematically saves significant space.
• Architecture Upgrade: True-Shape Engine v2. The Dense Packing algorithm has been entirely rebuilt:
  • Math Engine Rasterization: Completely bypasses Illustrator's infamous bounding box inflation bug. Objects are now rotated mathematically in memory, ensuring perfect contour hugging without false collisions.
  • Two-Pass Placement: The system now acts like an intelligent mason: Pass 1 places large objects to build the structural landscape, and Pass 2 executes a fine-search to pour tiny objects into the remaining gaps.
• Major Bug Fix: Fixed a bug with memory leaks and uneven filling of cells when using Offset Odd/Even Rows in Grid Layout.

Version 1.1.2 (November 22, 2025)

This update focuses on maximizing packing density, refining algorithm precision, and unifying rotation logic for Dense Packing.

• Dense Packing Optimization & Quality Boost. The True-Shape nesting engine received a major upgrade. Geometry decomposition now merges adjacent sectors, speeding up calculations by 5-10x. The "Safety Valve" (fallback to coarse packing) has been removed, ensuring the algorithm always performs a full-quality analysis regardless of complexity.
• Enhanced Rotation Logic. The "Allow 90° turn" feature now evaluates three orientations (0°, 90°, and 270°) instead of just two, providing better fitting opportunities in Dense Packing.
• Grid Layout Fixes. Fixed a coordinate drift issue where objects would shift visually when using "Size Limit OFF" combined with large "Vary Size" values. Scaling now occurs relative to object centers to ensure perfect alignment.
• Raster & Placed Item Support. Fixed "Select at least 2 objects" errors when working with images. The plugin now includes robust fallback mechanisms to correctly detect bounds for Raster and Placed items.

Version 1.1.1 (October 17, 2025)

This is a major update focused on radical algorithm improvements, new features, and overall stability, making Arrange Master a truly professional-grade tool.

• Complete Overhaul: Dense Packing Algorithm. The true-shape nesting engine has been rewritten from the ground up. It now uses a "Global Free Space Analysis" architecture, allowing it to see and utilize not only holes inside objects but also the complex empty spaces that form between multiple objects. This results in significantly denser and more intelligent layouts.
• New Feature: Dynamic Simplification. The Dense Packing algorithm is now equipped with a powerful safety valve ("Pre-emptive Complexity Control") that detects and prevents computational explosions. This makes the algorithm robust and stable, eliminating freezes even on extremely complex layouts or with high 'Analysis Precision' settings.
• New Feature: Single Item Fill. The Grid Layout panel now includes a powerful mode to fill the container with copies of a single selected item, using the efficient Skyline algorithm for a dense, organic pattern.
• New Feature: Staggered Grid Offsets. The Grid Layout now includes "Offset Even/Odd Rows" options to easily create staggered, checkerboard-style patterns.
• Major Bug Fix: Dense Packing "Bottom-Up" Mode. The "Bottom-Up" direction for Dense Packing has been completely fixed using a robust "Flip Trick" architecture. It now produces a perfectly mirrored, high-quality layout that correctly utilizes all internal and external cavities.
• UI/UX Improvements: The Grid and Greedy layout panels have been significantly redesigned for better clarity, compactness, and usability. Controls are now contextually disabled/enabled based on the selected mode.
• Infrastructure: Windows & macOS Installers. The project now includes a professional, digitally-signed installer for Windows and a clear manual installation package for macOS, ensuring a smooth setup process for all users.

Version 1.0.1 (October 10, 2025)

This update focuses on adding powerful new features for organic layouts and significant performance optimizations.

• New Feature: Dense Packing ("True-Shape Nesting"). The Greedy Layout now includes an advanced mode that analyzes the true vector shape of objects, allowing for incredibly tight and natural-looking packing that fills concave areas.
• New Feature: Analysis Precision. A new control for Dense Packing that allows users to balance performance versus packing quality.
• New Feature: Align Final Edge. An optional post-processing step for Greedy and Dense Packing modes to clean up the final "ragged" edge of the layout.
• New Feature: Vary Rotation for Shape Respect. The Shape Respect layout now includes a "Vary Rotation" setting to add organic randomness to placements inside complex shapes.
• Optimization: The Dense Packing algorithm now caches the complex geometry analysis. Subsequent clicks on "Arrange" or "Randomize" within the same session are now significantly faster.
• UI/UX Improvements: The user interface for all panels has been polished for better alignment, spacing, and clarity. Tooltips have been updated to be more descriptive.
• Bug Fixes: Fixed numerous bugs related to session management, object transformation, and UI rendering to improve overall stability.

Version 1.0.0 (September 15, 2025)

• Initial public release.
• Introduced the four core layout methods: Grid, Knolling, Greedy, and Shape Respect.
• Established the robust session-based workflow with "Ok" and "Cancel" states to protect user's original artwork.
• Implemented basic controls for each layout method, including spacing, rotation, and fill direction.