In Harmony¶

Harmony is where OTS speaks its native language. The interchange format's canonical space is Harmony's OGL convention — Y-up, right-handed, metres — so nothing is swizzled on the way in or out. Every other application converts to what Harmony already uses.

Launching¶

Run the OctoTransformSync script from the Scripts toolbar. The window opens on top of Harmony and stays there; running the script again while it's open just raises it.

The vocabulary in the window is Harmony's: the lists say PEG and PEGs, and the import button says Apply to PEGs.

The four pages¶

Two formats across the top, two directions below them — every page you can reach in Harmony:

Pivot · ImportPivot · ExportAnimation · ImportAnimation · Export

A rest skeleton about to be built. Build Skeleton creates the pegs; Create Cameras lights up because this file carries one.

The pegs you scanned in, with the Rig column and the Scale option. No frame range — a .pvt has no animation.

The match tree, with a checkbox per row and the three actions: Apply to PEGs, Create Rig, Create Cameras.

Same list as the .pvt export — one scene, one grouping — plus Start / End and Scene range.

What OTS reads from a peg¶

For each exported peg, OTS records:

Its path in the node graph, and its nearest exported ancestor as its parent.
Its pivot, in canonical metres.
Its transform, evaluated per keyed frame as a world matrix and made relative to that ancestor.
Its authoring modes — separate position, quaternion-path rotation, separate scale, 3D enabled — recorded as a hint.
If a CAMERA node hangs off it, the camera configuration.

Keyframes are collected from the peg's actual control points, plus the first and last frame of the export range. Bezier handles are read natively where the column type allows it, and reconstructed by sampling the curve where it doesn't.

The field ↔ OGL scale¶

Harmony works in fields, not metres, and the conversion between them isn't a constant — it depends on the scene's resolution, field of view, and aspect ratio. OTS asks the live scene for it at export and import time rather than hard-coding a number, which is why the Harmony adapter needs an open scene to do its work.

Harmony's camera clip planes are also in fields. Their original field values are preserved in the file alongside the converted distances, so a Harmony → anything → Harmony round trip returns the exact numbers you started with.

The "fake quaternion"¶

Harmony has a column type called QUATERNIONPATH, and it is not a quaternion.

It's a subclass of the 3D-path column, and it stores a path of three Euler angle components plus a velocity — not a (w, x, y, z) quaternion. Reading it as a quaternion produces nonsense.

So OTS always reads and writes a peg's rotation as Euler XYZ degrees, in every peg mode. Internally, the interchange format carries a real quaternion for rotation as well, computed from the baked world matrix; that one is order-independent and sidesteps Euler-order ambiguity entirely, and it's what the other applications prefer on import.

You don't have to do anything about this. It's here because it explains why a peg's rotation is handled the way it is, and why a naive quaternion read of a Harmony scene goes wrong.

Importing onto existing pegs¶

Apply to PEGs writes the animation onto matched, ticked rows.

Apply rewrites the peg's authoring mode

Before writing, OTS unlinks any 3D-path or quaternion-path column on the target peg, forces separate position / rotation / scale channels with 3D enabled, and writes fresh bezier curves.

The resulting values are correct and the curves are fully editable. But a peg that was authored on a 3D path is not on a 3D path afterwards, and that isn't undone by re-importing.

This is a deliberate trade-off: an arbitrary incoming curve can't be represented in Harmony's path columns without it. If the peg is something you hand-crafted and want to keep as-is, apply onto a Create Rig result instead and merge by hand.

The source_modes recorded in the file are a hint only — they describe how the peg was authored on the way out, and never change any value on the way in.

What Create Rig builds¶

Create Rig assembles a complete, tidy sub-graph rather than a pile of loose pegs:

A wrapper group named after the file, with a Multi-Port-In.
An external peg for the whole group, so you can move the result as one object.
One peg per item, with the rest pivot written into its pivot attributes.
Parent-to-child links following the file's hierarchy.
A composite fed by the leaves, and a Multi-Port-Out.
The group linked into the parent group's main composite.

The entire build is one undo step.

Create Cameras adds a peg plus a CAMERA node per camera, links the camera under its peg, and keys the peg from the file.

Notes and limits¶

Suffixes are stripped for matching. A Harmony peg named hip-P and a Maya joint named hip are treated as the same item, so the usual -P / -G / -C conventions don't break a round trip.

Harmony reads files a little more loosely. The Harmony adapter's readers don't run the same strict version check the Maya and Blender readers do, so a wrong-version file surfaces as a different error there. Re-export from the source application and it goes away.

The scene has to be open. Everything the Harmony adapter does — the field scale, the matrix bake, the node graph writes — runs against the live scene.