Duplicates the first child container and arranges the copies in a matrix grid, ellipse arc, or on a sphere surface.
Note: This plug-in is located in: Plugins -> Container plug-ins -> Tools
Performance tips:
This plug-in is designed to quickly create and arrange a certain amount of containers. If you are running on the Viz Engine Render Pipeline and using the same geometry, please consider using the Instancing plug-ins.
Changing only spatial parameters (spacing, radius, angles) triggers a reposition-only pass. The performance expensive clone/tree operation only runs when clone count, rows, or columns change.
This page contains the following topics and procedures:
Overview
The Cloner plug-in takes the first child of the container it is applied to and creates up to 3,000 copies, positioning them in one of three spatial arrangements. It is commonly used to build data-driven bar charts, grids, circular gauges, audience seating, and particle-style scatter layouts.
Matrix: Rectangular grid on a selectable plane (XY / XZ / YZ).
Ellipse: Arc or full ellipse with independent semi-axes and angle range.
Sphere: Surface distribution over azimuth × pitch ranges.
Quick Start
Create a group container and add the Cloner plug-in to it (Plugins > Container > Tools > Cloner).
Add one child under the group. This is the template to be cloned (for example, a cube, a rectangle, or an entire sub-tree).
Set Clones Count, Rows, and Cols. The effective count is
min(Count, Rows × Cols).Choose a Shape (Matrix, Ellipse, or Sphere) and adjust the corresponding layout parameters.
For Matrix mode, set Delta X / Y / Z to control spacing, and choose whether the delta represents per-step distance or total bounding box.
Parameter Reference
General
Parameter | Default | Range | Description |
|---|---|---|---|
Clones Count | 100 | 1 – 3,000 | Total number of clones to create. |
Clones Rows | 1 | 1 – 3,000 | Number of rows in the layout grid. |
Clones Cols | 1 | 1 – 3,000 | Number of columns in the layout grid. |
Shape | MATRIX | MATRIX | Spatial arrangement mode. |
Rename SubTrees | Off | — | When enabled, renames entire sub-trees of each clone (not just the direct child). |
Remove Excess Containers | Off | — | Automatically deletes clones that exceed the current count. When off, excess containers are hidden instead. |
Matrix Mode
Parameter | Default | Range | Description |
|---|---|---|---|
Plane | XY | XY · XZ · YZ | Which two axes are used for column/row layout. |
Delta X | 0 | ±10,000,000 | Spacing along X axis. |
Delta Y | 0 | ±10,000,000 | Spacing along Y axis. |
Delta Z | 0 | ±10,000,000 | Spacing along Z axis. |
Delta represents | Step | Step | Step: delta is the distance between each clone. Bounding Box: delta is the total extent, divided evenly among clones. |
Ellipse Mode
Parameter | Default | Range | Description |
|---|---|---|---|
R1 | 0 | 0 – 100,000,000 | Semi-axis one (horizontal radius). |
R2 | 0 | 0 – 100,000,000 | Semi-axis two (vertical radius). |
Min Angle | 0 | 0 – 360 | Start angle of the arc (degrees). |
Max Angle | 0 | 0 – 360 | End angle of the arc (degrees). |
Offset Angle | 0 | 0 – 360 | Additional rotation applied to each clone so it faces outward along the arc. |
Sphere Mode
Parameter | Default | Range | Description |
|---|---|---|---|
Radius | 100 | 0 – 100,000,000 | Distance from center to each clone. |
Min Azimuth | 0 | 0 – 360 | Longitude start (degrees). |
Max Azimuth | 360 | 0 – 360 | Longitude end (degrees). |
Min Pitch | −90 | −90 – 90 | Latitude start (degrees, south pole = −90). |
Max Pitch | 90 | −90 – 90 | Latitude end (degrees, north pole = 90). |
Actions
Action | Description |
|---|---|
Remove All | Deletes all cloned children, leaving only the original template container. |
Remove Only Excess | Deletes clones that exceed the current Clones Count. |
How It Works
Cloning: The plug-in iterates
Rows × Cols(capped at Clones Count). For each slot where a child container does not yet exist, it copies the previous sibling. Each clone is renamed sequentially. If Rename SubTrees is on, the entire sub-tree of each clone is also renamed.Positioning: Based on the selected Shape, each clone's position and rotation are calculated:
Matrix: Steps through rows × cols applying X/Y/Z offsets. In Bounding Box mode, deltas are divided by the row/col count.
Ellipse: Distributes clones evenly on an elliptical arc between Min Angle and Max Angle. Multi-row ellipses grow radii proportionally and shift in depth.
Sphere: Uses azimuth (longitude) across columns and pitch (latitude) across rows to place clones on a spherical shell. Each clone is rotated to face outward.
Change detection: Each frame, current parameter values are compared against cached values. Count/row/col changes trigger a full rebuild; spatial-only changes trigger a cheap reposition pass.
Excess handling: Containers beyond the current count are either hidden (
active = false) or deleted, depending on the Remove Excess Containers setting.
Usage Examples
Example 1: 5×3 Grid of Cubes
Container "CubeGrid" └─ Cloner (Shape: MATRIX, Count: 15, Rows: 3, Cols: 5, Delta X: 120, Delta Y: 120) └─ Cube (geometry: Cube, 100×100×100)Creates a five column, three row grid of cubes spaced 120 units apart on the XY plane.
Example 2: Circular Gauge (270° Arc)
Container "Gauge" └─ Cloner (Shape: ELIPSE, Count: 27, Rows: 1, Cols: 27, R1: 200, R2: 200, Min Angle: 135, Max Angle: 405) └─ Tick (geometry: Rectangle, 4×20)Places 27 tick marks evenly along a 270° arc, each rotated to face outward from center.
Example 3: Globe Markers
Container "Globe" └─ Cloner (Shape: SPHERE, Count: 50, Rows: 5, Cols: 10, Radius: 300, Min Azimuth: 0, Max Azimuth: 360, Min Pitch: -60, Max Pitch: 60) └─ Dot (geometry: Sphere, scale: 0.1)Distributes 50 markers across a sphere shell, covering ±60° latitude in a 10×5 grid.
Bounding Box vs Step mode: In Step mode, Delta values are the distance between adjacent clones. In Bounding Box mode, Delta values define the total extent of the grid (the spacing is computed automatically). Switching modes without adjusting values can cause clones to overlap or spread unexpectedly.
Technical Notes
The effective clone count is
min(Clones Count, Rows × Cols).The first child is always the template (it is never deleted by cleanup actions).
GUI parameters are dynamically shown/hidden based on the selected Shape (matrix parameters are hidden in sphere mode and vice versa).
Clone naming is sequential:
Clone_1,Clone_2, etc.For large clone counts (1000+), enable Remove Excess Containers to prevent hidden containers from consuming memory.
