Precomp surgery

Precomp surgery

Inherited projects often need restructuring: a precomp that shouldn't be one, or a comp to copy with all its nested precomps unlinked. After Effects' own commands and free scripts can drop what the precomp layer did and silently break expressions such as comp("Logo").layer("Title") or thisComp.layer(3). ae_precomp_surgery does it exactly, or not at all.

Ask for it in plain words: "Un-precompose Logo_Lockup and prove nothing changed." or "Make a deep duplicate of Endcard for the French version."

Un-precompose

action: "unprecompose" brings a precomp layer's layers into its comp, at its place.

• Transform: a null carries the precomp layer's anchor point, position, scale and rotation, keyframes and expressions included, and the moved top-level layers are parented to it. Parents inside the precomp are kept. bakeNull leaves the null out when the transform does nothing.
• Time: layers move by the precomp layer's start time and are trimmed to its span. A layer entirely outside it is moved switched off.
• Names that are already taken in the comp get a number.
• Expressions are read with a real JavaScript parser and rewritten by position: in the moved layers thisComp.layer("x") points at the moved copy, thisComp.layer(3) at its new index, and thisComp.width (and every other comp attribute) becomes comp("<precomp>").width. References by index to the comp's own layers, from anywhere in the project, follow the layers that move down.
• Track mattes and Layer Control parameters are pointed at the moved layers.
• One visible layer takes over the precomp layer's opacity and blend mode.
• The source comp is kept. removeSource removes it, only if nothing else uses it.

Deep duplicate

action: "deep_duplicate" copies a comp and every nested precomp, each once (a precomp used in several places maps to one copy). The copies' precomp layers point at the copies, and comp("X") in the copies is rewritten when X is in the tree; references to comps outside it stay. Copies get a suffix (default " copy", plus a number when the name is taken). Footage and solids are shared, not copied.

The copies are made next to their originals. After Effects records every move into a folder as an undo step of its own, so moving them (for example with ae_move_items) is left to a separate step.

Refused, with the exact reason

When the result can't be reproduced exactly, nothing happens and the reason is given. For example:

• on the precomp layer: effects, masks, layer styles, time remapping, time stretch, track mattes, 3D, collapse transformations, motion blur or frame blending; its blend mode or opacity when the precomp has more than one visible layer;
• layers in the precomp that would interact with the comp's other layers (blend modes, adjustment layers, Preserve Underlying Transparency, cameras, lights, 3D layers);
• different frame rates or motion blur settings, Essential Graphics overrides, layers reaching outside the precomp's frame where that part would show;
• expressions that can't be rewritten safely: names or indices computed while the expression runs, a layer's own index, wiggle or random when the index changes, time when layers move in time, toComp and similar, references to the precomp layer itself, ambiguous comp names, expressions that already have an error.

override: ["expressions"] or ["bounds"] goes ahead anyway: those items are still listed and left as they are, and the pixel proof decides. dryRun: true returns the plan only: what moves, what is renamed, every expression rewrite (before → after) and every problem.

Proof first, then the change

1. A checkpoint is saved. The project must be saved.
2. Reference frames are rendered: by default 6 frames across the precomp layer's time span, first and last included; for a deep duplicate, 5 across the work area.
3. The surgery is rehearsed on a scratch copy (a duplicate of the parent comp; for a deep duplicate, the copies) and compared with the original pixel by pixel, the same comparison as Proven edits. The scratch copy is removed again.
4. Only when the result is IDENTICAL is the same surgery applied to your project, in one undo group, and checked layer for layer against the rehearsal. If it doesn't match, it is undone at once.

DIFFERS means nothing was applied. The result lists the frames that differ, the largest difference, a difference image and the likely cause (for example a scaled precomp layer: the precomp was resampled as a whole, while the moved layers are transformed once).

The way back

After Effects can split such an undo group into several steps (seen with layer copies and source replacements), so ae_undo may not be enough. The result names the exact way back instead:

• Un-precompose: restore the checkpoint saved first (ae_checkpoint restore, with its id).
• Deep duplicate: it never changes the originals and only adds copies, so {action: "remove_copies", id} removes exactly the copies it lists. It refuses while anything outside them uses one.

Honest limits

• The pixel proof covers the parent comp (or the copied tree) at the sampled frames. Expression rewrites in other comps are exact text edits, not proven with pixels.
• As with every proof: audio, the comp's background colour and the times between the samples are not compared.