image-20240923-063053.png

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

  1. Create a group container and add the Cloner plug-in to it (Plugins > Container > Tools > Cloner).

  2. Add one child under the group. This is the template to be cloned (for example, a cube, a rectangle, or an entire sub-tree).

  3. Set Clones Count, Rows, and Cols. The effective count is min(Count, Rows × Cols).

  4. Choose a Shape (Matrix, Ellipse, or Sphere) and adjust the corresponding layout parameters.

  5. 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
ELIPSE
SPHERE

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
Bounding Box

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

  1. 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.

  2. 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.

  3. 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.

  4. 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.