copyToDocument

Copies the specified Properties from the source Document to the target Document, leaving originals in the source. Dependencies of the source properties will also be copied into the target. Returns a Map from source properties to their counterparts in the target Document.

Example:

import { copyToDocument } from '@gltf-transform/functions';

// Copy all materials from sourceDocument to targetDocument.
const map = copyToDocument(targetDocument, sourceDocument, sourceDocument.listMaterials());

// Find the new counterpart of `sourceMaterial` in the target Document.
const targetMaterial = map.get(sourceMaterial);

Copying a Mesh, Animation, or another resource depending on a Buffer will create a copy of the source Buffer in the target Document. If the target Document should contain only one Buffer, call unpartition after copying properties.

Repeated use of copyToDocument may create multiple copies of some resources, particularly shared dependencies like Textures or Accessors. While duplicates can be cleaned up with dedup, it is also possible to prevent duplicates by creating and reusing the same resolver for all calls to copyToDocument:

import { copyToDocument, createDefaultPropertyResolver } from '@gltf-transform/functions';

const resolve = createDefaultPropertyResolver(targetDocument, sourceDocument);

// Copy materials individually, without creating duplicates of shared textures.
copyToDocument(targetDocument, sourceDocument, materialA, resolve);
copyToDocument(targetDocument, sourceDocument, materialB, resolve);
copyToDocument(targetDocument, sourceDocument, materialC, resolve);

If the transferred properties include ExtensionProperties, the associated Extensions must be added to the target Document first:

for (const sourceExtension of source.getRoot().listExtensionsUsed()) {
    const targetExtension = target.createExtension(sourceExtension.constructor);
    if (sourceExtension.isRequired()) targetExtension.setRequired(true);
}

Root properties cannot be copied.

TextureInfo properties cannot be given in the property list, but are handled automatically when copying a Material.

To move properties to the target Document without leaving copies behind in the source Document, use moveToDocument or dispose the properties after copying.