Ribbon Handling

Web handling moves continuous material: a single endless strip of paper, film, foil, textile or sheet coil. One roll pays out the strip, which runs over rollers before another roll takes it up. Slitters, rewinders, coaters and laminators use this kind of material flow. It is the only kind that does not move a sequence of discrete parts.

The components are called Ribbon Roller, Ribbon Winder, Ribbon Dancer and Ribbon Path. The word web stays the industry term for the material in this page, but the Web* prefix is reserved for the browser-HMI marker components (WebSensor, WebError, …), so the material-handling components carry Ribbon* instead.

Four components describe the web geometrically rather than procedurally. You place rollers and list them in running order; the viewer computes the web:

Ribbon Roller — a roller the web runs over. Give it a rotational drive and it pulls the web; without one it spins at the speed the web imposes on it, so a small idler visibly turns faster than a large one.
Ribbon Winder — a roller whose diameter changes: the unwinder shrinks as the web leaves it, the rewinder grows as the web arrives. It reports diameter, wound length, empty and full back to the PLC.
Ribbon Dancer — a roller that travels on a guide and stores web, so two drives on one machine can run at slightly different speeds without the web going slack or tearing.
Ribbon Path — the web itself: the ordered list of rollers it runs over, and its width.

The web follows these rules:

The path is computed, not authored. The straight runs between rollers and the wrap arcs around them are worked out from where the rollers are and how big they are. Move a roller and the web follows it; nothing about the shape is stored in the file.
The web is taut by default. It lies exactly on the tangents and wrap arcs, as an industrial web does. This needs no physics solver and gives the same result every run. Web tension is opt-in: give the material a stiffness to track strain between driven rollers. A slack web can then sag, and colour shows where it is too loose or too tight.
Only rollers move the web. The path has no line drive to reference. A roller with a rotational drive pulls the web at that drive’s surface speed, and every other roller follows. As on a real converting line, this allows two drives to run at slightly different speeds, with a dancer between them.

The path is computed from the rollers. Driven rollers and the dancer bound the tension zones; idlers only follow.

What drives the web

A roller is driven when a rotational drive sits on the same object and turns about the roller’s own axis. Its surface speed (turning rate times radius) is the web speed. Every other roller follows the web.

That single rule covers every case the old line drive did, and several it did not:

A nip or pull roll with a drive at a fixed speed sets the line speed.
A centre-driven winder with a drive turns at a constant rate, so its surface speed rises as its roll grows — exactly what a real centre winder does, and the reason a dancer is needed downstream of it.
Two rewinders on one slitter may run at different rates. They are no longer a modelling error; the dancer between each of them and the nip takes up the difference.

Put the drive on the roller object itself, not on a parent, and give it a rotation direction about the same axis the roller turns about. A linear drive, or one turning about a different axis, is reported in the console and ignored — the roller stays a follower.

Key properties

Ribbon Path

Property	Description
Rollers	The rollers the web runs over, in running order. The first and the last entry are the two ends of the web and are normally winders. A Ribbon Dancer in this list splits the web into two sections that may run at different speeds.
Ribbon Width Mm	Width of the web, measured across the rollers.
Ribbon Thickness Mm	Thickness of one layer of the material. It lifts the web off the roller surface and determines roll growth. Give the winders on this path the same value because they carry the same material.
Texture Length Mm	How much web one repetition of the surface pattern covers. The pattern scrolls by the distance the web travels, making its motion visible. A larger value gives a coarser pattern that appears to move more slowly.
Samples Per Meter	How finely the web strip is subdivided, in points per metre of path. Raise it when a tight wrap looks angular, lower it on a very long run. On a slitter, give every strip the same value — it is what makes them cut at exactly the same place. A very long web has its density reduced automatically, which puts it on a coarser grid than its siblings and moves its cut slightly; the console reports that, and the answer is a lower value for the whole slitter.
Material	Optional. A node whose material the web copies, such as a printed pattern or coloured film. It references a scene object, not a material alone. The web copies the object’s first textured material, including its normal and roughness maps. The source part is never changed. Without it, the web has a plain paper-white surface.

Ribbon Roller

Property	Description
Radius Mm	Contact radius of the roller. Left at 0 it is measured from the roller’s own geometry, which is usually what you want for imported CAD.
Axis	The axis the roller turns about. Every roller of one web path must be parallel — a web path is a flat problem, and angled web guides or turn bars are outside what it models.
Ribbon Side	Which side of the roller the web runs on. Leave it on Auto — for every normal machine Auto picks the short wrap, the only one a real web can take. Set Left or Right by hand only for an S-wrap or a wrap of more than 180°, where the short wrap is the wrong one. Left and Right are the turning sense seen looking along the +Axis direction: Left counter-clockwise, Right clockwise.
Rotation Direction	Either 1 or -1. Set it to -1 when the roller visibly turns against the web, which happens when an imported CAD axis points the other way. It only changes what you see; it never changes the web speed.
Spin Mode	How the roller shows that it is turning. Transform turns the roller object. Texture keeps it still and scrolls the pattern on its barrel. On a textured roller, this looks the same at a glance and needs no per-frame work. This reduces work on machines with dozens of idlers. It applies only to rollers without a drive; a driven roller is always turned by its drive.
Mantle Mesh	The part that scrolls in Texture mode, normally the roller’s barrel. If empty, it uses the roller’s own mesh or the largest textured child part outside a `Faces` group. The end discs therefore stay still while the barrel appears to turn.

Ribbon Winder

Property	Description
Core Radius Mm	Radius of the bare core or sleeve the material is wound onto. The default 76.2 mm is the 3 inch core of the converting industry.
Ribbon Thickness Mm	Thickness of one wound layer. Together with the core radius this is what determines how fast the roll grows or shrinks. It must be the same value as on the Ribbon Path — it is the same material.
Initial Wound Length Mm	How much material is on the roll at the start and after a reset. -1 (the default) means a full roll exactly as modelled — the length is read off the modelled outer radius, so a full parent reel needs no number typed in. 0 means an empty core, which is what a rewinder starts at. Any other value is the length in millimetres on the roll.
Max Diameter Mm	The diameter at which the roll counts as full. Reaching it stops the web and raises the Full signal. 0 means no limit.
Roll Mesh	Which part grows and shrinks with the roll. Usually left empty: the winder object is the roll, and it is scaled directly. Model the core as a sibling next to it, never as a child — a child would scale with the paper and the core would visibly grow. Set this field only when the roll is a separate part or the winder object has no geometry of its own; a winder with nothing to scale gets a plain cylinder so it is never invisible.
Diameter Mm / Wound Length Mm / Empty / Full	Signals written back to the PLC. Diameter and wound length are written when they actually change; empty and full on the edge.

Ribbon Dancer

A dancer is a Ribbon Roller that also travels on a guide. Its carriage stores web delivered by the upstream roller but not taken by the downstream roller. The PLC regulates the carriage position.

Property	Description
Travel Axis	The direction the carriage runs in, given in the frame of whatever the dancer hangs under — the same axis letters as the roller Axis. Place the dancer so that moving along the positive axis lengthens the web path — that is the direction “more material stored” points in.
Travel Min Mm / Travel Max Mm	The two mechanical stops, measured from the home position. Min is zero or negative, Max is zero or positive.
Home Mm	Where the carriage rests and returns to on reset. 0 means exactly where you modelled it.
Strands	How many runs of web pass through the carriage. 1 is a single pass over the roller; 2 (the default) is the usual loop that goes down to the carriage and back up again. One millimetre of travel then stores that many millimetres of web.
Position Mm / At Min / At Max	Signals written back to the PLC. The position is the regulated variable of a web tension controller; the two flags are the mechanical stops.

At a stop the dancer does not halt the line. At Travel Max it only stops the store from filling further — the upstream section drops to the downstream speed — and at Travel Min only from emptying. The web keeps running at the slower of the two, and the moment the PLC reverses the difference the carriage comes free again. A dancer that stopped everything would deadlock: with both sides at zero, nothing could ever move it back.

Use one dancer per web path. A second one, or a dancer at either end of the roller list, is ignored and reported. On a slitter, give each strip its own dancer unless the dancer sits before the cutter. A dancer shared by strips pulled by different rewinders has no single speed difference to store. It stays at its home position.

Web tension

Web tension measures how hard the material is pulled, the quantity used to regulate a converting line. It is optional. A Ribbon Path with Tensile Stiffness left at 0 keeps the same motion behaviour, sample for sample.

With a stiffness set, the path is divided into zones between consecutive driven rollers — a driven roller is where the web cannot slip, so it is where tension can change. Idlers do not divide zones; the dancer does. Each zone carries one strain: positive when the material is stretched, negative when there is more material in the span than fits taut. The two are the same number, and everything visible follows from it:

Stretched (strain > 0): tension is stiffness × width × strain, and the web stays on its tangents.
Slack (strain < 0): the tension is zero and the surplus length sags in the free runs between rollers. The web still lies on every roller; only the straight runs hang.
Strain is integrated from the speed difference across the zone, using the standard span model of web-handling engineering. A downstream nip running 1 % faster than the upstream nip builds up about 1 % strain. The time depends on the zone length divided by the web speed.

The dancer as a tension setter

A loaded dancer sets tension as it does on a real machine. Set Load N to the cylinder or weight force on the carriage. The tension in both adjacent zones immediately becomes load ÷ strands. The load does not move the carriage; only the speed difference does. At equal speeds, changing the load changes Tension N while the carriage stays still. Changing a speed moves the carriage while tension stays constant. This is the force-in, position-out interface of a pneumatic dancer. A tension controller in the PLC is written against it.

Key properties

On the Ribbon Path:

Property	Description
Tensile Stiffness N Per Mm Width	The one number that turns tension on. Force per millimetre of web width at 100 % strain — the secant of the strip tensile curve at the working point, which is how nonwoven and tissue data sheets state it. 0 = no tension model.
Basis Weight Gsm	Grammage of the material. Used to report the specific tenacity (N·m/kg) so materials of different weight can be compared; it does not change the simulation.
Target Tension N Per M	The set tension per metre of width. The unwinder pays the web out at this tension, every zone starts at it after a reset, and the colouring is centred on it. 1 PLI is 175.1 N/m.
Tolerance Band Percent	Half-width of the band around the target inside which the web is not coloured.
Min Strain Percent	Below this the zone counts as slack. 0 means: as soon as there is surplus material.
Max Strain Percent	Above this the zone counts as overstretched. For a nonwoven this is the yield point of the secant, and it is where the linear model stops being true.
Break Force N Per 50mm	The strip tensile strength. Reaching it breaks the web: the zone freezes and Is Broken is set until a reset.
Enable Sag	Show the surplus of a slack zone as a hanging run.
Tension Coloring	Colour the web outside the tolerance band.
Tint Strength	How strongly the colour overlays the material, 0–1.
Deformation Scale	Display only. Multiplies the sag depth so a realistic fraction of a percent becomes visible; never changes the tension or any signal.
Show Tension Labels	A label per zone with N/m, PLI and strain, and a force arrow plus travel bar on a loaded dancer.

On the Ribbon Dancer: Load N — the force on the carriage, 0 = no tension setting — and Tension N, written back to the PLC.

What you see

Inside the tolerance band, the web is not coloured, so your material appears unchanged. Colour marks zones outside specification:

State	Condition	Colour on the web
Slack	strain below Min Strain	cyan, fully saturated, pulsing — and the run sags
Below band	under the tolerance band	blue, deeper the further from the band
In band	inside the band	none
Above band	over the tolerance band	orange, deeper the further from the band
Overstretched	strain above Max Strain	magenta, fully saturated, pulsing
Broken	strain at the break force	magenta, and the label says so

The alarm colours carry an emissive component so they stay readable on a dark or black material. The band edge is a hard edge, not a gradient: a zone either has colour or it does not.

Signals

The path writes Tension N, Specific Tension N Per M and Strain Percent for its last zone — the usual place for a load cell, just before the rewinder — and Is Slack, Is Overstretched and Is Broken as any zone. The dancer writes its own Tension N.

What is not modelled

Tension is off on the strips of a slitter (a path with Slit At Roller or Full Width), because the strips share one web up to the cut and would need one common strain; a warning says so once. A web running backwards freezes its strain until it runs forward again. The pattern on the web does not stretch with the material, and only one dancer per path sets tension, as before.

The internal demo document DemoRibbonTension (Development project) shows all of it: a braked unwinder, three driven nips with a loaded dancer between the last two, and a driven rewinder. It comes with a small control window — a panel that is always open, can be moved and collapsed but never closed — with three latched keys, Schlaff / Normal / Überdehnt, that set the second nip to 784, 800 or 816 mm/s, a Last ×2 key that doubles the dancer load only while it is held, a Reset key that restores the setpoints, and two sliders for the nip speed and the dancer load. Press Schlaff and the zone between the first two nips sags cyan; press Überdehnt and it turns magenta with the web keeping its shape; hold Last ×2 and the dancer’s tension doubles while the carriage stands still.

In the demo, Reset restores the setpoints, not the strain. An overstretched web stays overstretched when both nips return to the same speed. Strain is the integral of the speed difference, so equal speeds hold the existing strain. To bring a zone back into the band, briefly run the downstream nip slower, as on a real machine.

The window itself is a project plugin, defined in code in projects/Development/plugins/index.ts and bound to the document through scriptRef in the project file — the same way any project adds its own HMI. The building blocks (ControlWindow, latched, momentary and slider controls) are part of the open viewer, so any project can use them.

Quick Start

Model or import the rollers. Give them a common axis, and make sure each one is a separate object.
Add a Ribbon Winder to the roll at each end of the web, and a Ribbon Roller to everything in between. The winder object is the roll itself; put its core next to it as a sibling.
Add a rotational drive to the roller that pulls the web — the nip, or the rewinder on a centre-driven line — turning about the same axis as the roller.
Add a Ribbon Path on its own object. Add the rollers to Rollers in running order, starting at the unwinder.
Set Ribbon Side on each roller so the sides alternate wherever the web changes direction.
Run it. The web moves, the followers turn, the parent roll shrinks and the rewound roll grows.
Where two drives pull the same web at different rates, put a Ribbon Dancer between them in the roller list and set its travel axis and stops.

Slitting: several webs, one parent roll

A slitter cuts one wide web into several narrower strips, each going onto its own rewinder. Model it as one web path per strip, all of them naming the same unwinder and the same rollers up to the cutter in their Rollers list, and set Slit At Roller to the cutter with Full Width set to the width of the uncut web. The viewer then draws one full-width web up to the cutter and each strip in its own lane behind it. Leave Ribbon Side on Auto unless a roll must wind a specific way: Auto always picks the wrap a real web can take.

The cut is where the web meets the cutter, not where it leaves it — that is where a real blade sits. It matters because two strips wrap the cutter differently on their way to their own rewinders: cut where the web leaves the roller, the full-width web and one of the strips would both be drawn on part of that roller and would flicker against each other.

Up to the cut the strips are one web, so they must wrap every shared roller on the same side, and normally they do. If the rollers after the cutter are placed so that one strip turns left there and the other right, Auto resolves a shared roller differently for the two strips; the console reports that once, naming both webs and the roller. The web keeps running — move the roller that causes the opposite turn, or set Ribbon Side explicitly on the shared rollers.

Paths that share a roller are treated as one machine. The shared roll is consumed once rather than once per strip, and when it runs empty — or when any rewinder reaches its maximum diameter — every strip stops at the same moment. The strips do not have to run at the same speed: each one reads the roller that pulls it, so two rewinders at different rates are a normal machine, and the dancer between each of them and the cutter takes up the difference.

The internal demo document DemoRibbonSlitter (Development project) uses 3 mm material. It has one parent roll, four idlers, a driven nip, a dancer per strip and two driven rewinders. The rewinders turn at a fixed rate. They start slower than the nip, fill their dancers to the upper stop, then overtake it as their rolls grow. This demonstrates the dancer’s role within a couple of minutes.

Building it in Unity and exporting it

Since realvirtual 6.3 the same four components exist in realvirtual for Unity (Professional), with the same names, the same fields and the same units. A converting machine is therefore authored once: you build it in Unity, export the GLB, and the browser runs it — there is no ribbon-specific export step and nothing to re-wire afterwards.

Two design decisions keep Unity and browser behaviour consistent:

Unity computes in the glTF coordinate frame. Axis letters, Ribbon Side, Rotation Direction and Travel Axis mean the same thing on both sides, so nothing has to be flipped by hand after an export. (Unity mirrors X on export and maps RotationY to glTF -Y; a port that ignored that would run a machine built about the Y axis backwards.)
Nothing about the path geometry is exported. The tangents, the wrap arcs and the band are solved from the roller poses and radii, identically on both sides. Only the authored configuration travels in the document; the runtime state does not.

An automated roundtrip test checks this. Unity builds the demo slitter about the X axis and a second variant about the Y axis with Travel Axis X. It runs each for two seconds of simulation and records every roller angle, surface speed, wound length, dancer position, path length, cut point and wrap side. The browser then loads both exported documents and runs its own simulation with the same timestep and tick count. It must reproduce those numbers to within 0.5 % with the signs exact.

What to check after an export

Symptom	Cause
The web runs backwards (rewinders pay out from an empty core, everything stops)	The drive turns the wrong way for its roller axis. Set Reverse Direction on the drive. This is the usual finding after rebuilding a machine about a different axis.
A roller does not turn although it has a drive	The drive is linear, or its axis is not parallel to the roller axis. The console names the roller and the deviation.
A field you set in Unity has no effect in the browser	It is not part of the Open Digital Twin Format for that component. Runtime status values are deliberately not exported — the browser recomputes them.

When a web does not move

What you see	What it means
The web is shaped correctly but nothing moves	No roller of the path has a rotational drive on it, or the drive is not running. The console names the path.
A roller with a drive does not pull the web	The drive is linear, or it turns about a different axis than the roller. The console names the roller.
The dancer sits at a stop and does not come back	The two sides are running at the same speed, so nothing moves it. The line keeps running; reverse the difference to bring it back.
A shared dancer stays at its home position	It is shared by strips whose rollers are pulled by different drives. Give each strip its own dancer, or move it before the cutter.
The web is missing and the console names a roller	One entry of Rollers does not resolve. The rollers themselves stay where they are.
The console says a winder is in the middle	A winder is an end of a web. Move it to the first or the last position, or make it a web roller.
The console says a roller deviates by some degrees	The rollers of one path must be parallel within 2°. Check the axis of the roller named in the message.
The console says there is no tangent between two rollers	Two rollers overlap, or one is inside the other. Move them apart, or check their radii.
Everything stops and Empty is set	The unwinder is down to its bare core. Reset the simulation or set a larger Initial Wound Length Mm.
Everything stops and Full is set	A rewinder reached Max Diameter Mm.

Ribbon Handling

What drives the web

Key properties

Ribbon Path

Ribbon Roller

Ribbon Winder

Ribbon Dancer

Web tension

The dancer as a tension setter

Key properties

What you see

Signals

What is not modelled

Quick Start

Slitting: several webs, one parent roll

Building it in Unity and exporting it

What to check after an export

When a web does not move

See also