BWrap documentation

Installation

Use Blender 4.5 or later. Install BWrap directly from the downloaded ZIP. See the Blender installation guide.

1. Download the correct BWrap package: Free or Full.
2. Disable or remove any older BWrap installation. Do not keep Free and Full enabled together.
3. In Blender open Edit → Preferences → Get Extensions.
4. Open the Extensions menu and choose Install from Disk….
5. Select the BWrap ZIP and enable the extension.
6. Restart Blender once after the first installation.
7. Open the 3D Viewport sidebar and select the BWrap tab.

General workflow

BWrap works best as an iterative setup-and-check process rather than a single blind solve.

1. Choose the Template. Select a single Mesh or a Collection of meshes whose topology you want to keep.
2. Choose the Target. Select a Mesh or Collection containing the scan, sculpt or character surfaces you want to match.
3. Build the workspace. Use the two-view layout so both meshes stay easy to inspect.
4. Add point pairs. Start a batch on either side, then match the landmarks in order on the other side. Guide every disconnected part, starting with major anatomical landmarks.
5. Run an early wrap. Use the Fast preset to find correspondence problems before spending time on a final solve.
6. Protect difficult regions. In Full Edition, use Exclude, Keep Shape, Lock in Place and open-edge controls where the general solve should behave differently.
7. Run the final wrap. Free uses Fast with fixed settings. In Full, choose the quality level and Conform Strength that suit the asset.
8. Refine and apply. Nudge problem regions, refresh points for another pass when needed, then keep the result as an editable Blender mesh.

Core concepts

Setup and Workspace

Choose your meshes under the separate Template and Target headings. In Full, choose Mesh or Collection independently. Free uses one Template mesh and one Target mesh. Full adds Mesh/Collection, Collection/Mesh and Collection/Collection inputs.

Main panel order: Setup, View, Points, Weight Groups, Wrap, Refine, Texture Transfer. Each can be collapsed independently. Loops appears in Edit Mode; Settings and Advanced remain inside Wrap.

Modifiers and visible point placement

In the single-mesh workflow, Template point placement supports modifiers that preserve vertex and face identity. Disable topology-changing Template modifiers, or apply them on a copy before creating points. Target modifiers can remain enabled. Collection Templates have stricter neutral-state requirements below.

Full-body wrapping with multiple meshes — Full

In BWrap Full, use a Template collection for separate parts of a character or asset, such as a MetaHuman’s head and body. The Target can be one high-resolution mesh or several meshes in its own collection. Objects are assembled only for the calculation; Blender meshes are not joined or reordered.

1. Put the intended Template meshes into one collection. Use a single LOD. If the Target has several parts, put them into another collection.
2. Prepare a neutral Template: zero expression shape-key values, put armatures in Rest Position and disable other Template modifiers in the viewport. Relative shape keys can remain on the meshes.
3. Choose Collection under Template and assign it. Choose Mesh or Collection under Target and assign that input. Check the listed members. Hidden objects are still members; objects excluded from the current view layer produce an error. Shared or library-linked Template mesh data is not supported.
4. Enable Keep Seams Together and use Find Seam Connections. Optionally limit matching with a seam vertex group or restrict each Template to a particular Target mesh.
5. Build the workspace. Add landmarks on each disconnected part, including matching neck, shoulder, elbow, hip and knee locations where useful. Start on either side and match each batch in order.
6. Run Wrap, inspect the seam and fit, then use Nudge and Shift-smoothing. Each Template receives its own result shape key; Wrap Amount controls the set together.

Keeping the neck seam together

Seam matching finds corresponding boundary vertices that occupy the same position, within a world-space tolerance and with compatible normals. A small allowance handles coordinate rounding in exported head/body meshes. Accepted seam vertices share one position during Wrap and Nudge while remaining separate vertices on separate objects.

A seam vertex-group name limits matching to vertices in that group on each Template and can include interior duplicates. Missing groups contribute no vertices. Use this to avoid linking other nearby boundaries. Different vertex counts or unmatched edges cannot be turned into a matching seam automatically.

Near matches close at full Wrap Amount; intermediate strength retains a proportion of an initial gap. Later expression keys, rig deformation or independent object transforms can separate a seam again. If an older result has neck gaps, rerun Wrap from the original neutral Template with Keep Seams Together enabled. Restore that original first if the result was already applied.

Vertex groups, shape keys and character data

Vertex, face and loop order, UVs, materials, attributes and stored vertex weights remain on the original objects. In Full, Exclude, Pin and Keep Shape resolve by group name on each mesh; missing groups have zero weight. Linked seam vertices use the greatest mask weight among their members. Conflicting pinned seam positions are rejected.

Existing relative shape keys and their relationships remain intact. Applying the result preserves their local offsets from their relative keys; it does not adapt expressions to new anatomy. Absolute shape-key stacks and arbitrary posed/deformed collection Templates are unsupported. Custom drivers on a BWrap result must be removed before replacing that result; ordinary expression drivers are retained.

BWrap wraps geometry. It does not retarget MetaHuman DNA, skeletons, skinning, LOD relationships or Unreal export behavior. Check expressions and rig deformation separately after a major shape change.

Points and EdgeLoop Points

BWrap has two complementary guidance workflows. Use normal Points in Object Mode for isolated landmarks. In Full, use EdgeLoop Points in Edit Mode for continuous features such as lips, eyelids, cuffs, borders or other loops where a sequence of correspondence points is more useful than placing every point manually.

Normal Points — Object Mode

Start On can be Auto, Template or Target. In an overlapping single viewport, press Tab to switch from placing a batch to matching it. The split workspace is the clearest way to work.

Symmetry automatically queues mirrored counterparts in Full, including collection mode. Centerline points are not duplicated. Collection mode also offers a persistent Snap to Symmetry Plane toggle. Free displays these Full-only point controls as locked previews.

Free counts both completed pairs and pending landmarks on either side toward its 50-pair limit. To add a different landmark at the limit, remove an existing pair first.

Adjust mode

EdgeLoop Points — Edit Mode

Managing Loop Guides — Full

Set the sample count, replace or select stored loops, reverse the Target direction, recalculate the start or delete a guide. Each completed guide generates correspondence points automatically.

Organizing and reusing points

For collection Loop Guides, store one selected loop from a specific mesh on each side. Guides remember their owners. Generate / Update replaces that guide’s generated points, including manual changes to those points.

Wrap

Full also exposes solver Settings and Advanced controls: iterations, stiffness, sampling, smoothing, alignment, point influence, matching and symmetry. Free uses fixed Fast settings.

Start with Fast to check the point correspondence. BWrap smooths and normalizes guide influence to reduce local pinching; adjust mismatched points before increasing wrap quality.

Collection mode uses a result shape key on each Template, with shared Wrap Amount. The automatic Modify Mesh / New Object selector and automatic solver Symmetrize are single-mesh options; use collection Apply / Duplicate and explicit Mirror Points or Nudge symmetry instead.

Weight Groups

Pin is the Lock in Place control. Weight Groups and their tools are exclusive to Full.

Full Edition provides three painted per-region controls so difficult areas do not all have to obey the same fitting rule.

In collections, select matching group names on each mesh using Blender’s normal vertex-group tools. Detect Interior and the exclusion-preset editors are available only in the single-mesh workflow. Seam masks combine as described in Multiple meshes & seams above.

Refine

Nudge and Shift-smoothing follow connected Target triangles and relax the local Template surface. Attachments stay on their connected sheet instead of repeatedly jumping to whichever overlapping surface is nearest. The brush prepares only the neighborhoods it touches, and mirrored strokes share work.

Initial attachments can still choose the wrong sheet in an ambiguous overlap. Correct the landmarks or restrict a Template member to the intended Target mesh. Restart Nudge after changing that restriction. Separate objects, disconnected shells, unwelded boundaries and non-manifold Target edges act as barriers; use several smaller drags near complex folds.

These changes apply to Nudge and Shift-smoothing, including Nudge Points’ mesh movement. Automatic Wrap refinement stages are unchanged. Refinement is not a collision solver.

Workspace and View controls

The BWrap workspace is designed for comparing the Template and Target without one hiding the other.

Point colors and visibility

Left / Right / Center Colors distinguishes both the mesh side and the symmetry side: Template uses blue, teal and violet; Target uses orange, coral and gold. Left and right follow the symmetry frame, not the camera. Selected points keep their colors inside selection rings. Disable the option to restore blue/orange.

Template Pts and Target Pts independently hide markers, labels and pending points. Point Size works in Vulkan and OpenGL. The collection workspace displays all members on their appropriate side.

Output and continuing in Blender

Collection results

Each Template receives a separate BWrap result shape key. Wrap Amount controls the set together. Apply, Remove and Duplicate act on the saved result set, even after renaming objects or changing the current input selection. Apply and Duplicate use the full result. Finish or remove the existing result before switching to a different Template set. Cancellation and errors restore all members together.

Texture Transfer

Both editions can bake target textures, color attributes, tangent-space normal maps and cavity maps into the Template’s UV layout. The Template needs UVs; target texture sources also need target UVs.

Free outputs 256 × 256. Full offers 256, 512, 1024, 2048, 4096 and 8192 (8K). Both include sampling quality, margin and extrapolation, cavity controls, float output, preview materials and PNG / EXR / TGA / JPEG saving.

Collection texture transfer

Assign a source image to each Target mesh. BWrap creates a separate output image for each Template’s UV layout and respects per-part Target restrictions. Color attributes, normal and cavity transfer are also supported. Choose each output in the Image Editor and save it. Existing material assignments stay unchanged; shared atlases and UDIM workflows are not automated.

Free vs Full

Free supports 50 matched point pairs: 50 landmarks on the Template and 50 on the Target. Pending points on either side count toward this limit. Nudge symmetry moves existing points and geometry; point mirroring and Loop Guides are exclusive to Full.

Both editions support single-mesh wrapping. Full also supports collections with multiple meshes on either side. Free uses fixed Fast settings and Shape Key output, and still includes Apply and Create Object after wrapping.

Troubleshooting

Free reports too many points

Free supports up to 50 matched pairs. Oversized JSON imports are rejected without changing your setup. When an older scene contains more points, only the first 50 remain active. The complete list is preserved in a Blender Text named BWrap_Free_Point_Backup.json; save it from Blender’s Text Editor to recover the landmarks in Full.

BWrap fails to activate

Install the current BWrap version if you see an error mentioning _RestrictData and shape_keys. Remove the older edition before reinstalling, and only enable Free or Full at one time.

The Template moves to the wrong area

Check broad point correspondence first. Confirm left/right, front/back and major landmarks are paired correctly before adding more local points.

The result twists or slides

Add clearer point pairs around the region and confirm each Template landmark really matches the intended Target landmark.

A local region collapses or loses volume

In Full Edition, use Keep Shape or Exclude where appropriate. Also check whether nearby point pairs are pulling in conflicting directions and whether the Target actually contains the desired volume.

Open borders collapse or drift

Use Snap Open Edges to Target in Full Edition and add point pairs at meaningful border landmarks such as neckline corners, cuffs or seams.

A region keeps the Template shape when it should follow the Target

Check that Conform Strength is at the intended value and that the region is not painted into Keep Shape or Exclude.

The high-quality solve still looks wrong

Return to the setup. More iterations cannot repair swapped meshes, bad landmarks, wrong orientation or missing protection rules.

Garment/body intersections remain after wrapping

BWrap establishes the fit but does not replace downstream collision testing, thickness, skinning or cloth-simulation cleanup.

A tool stays highlighted after a crash/reload

Restart Blender once so interactive tools re-register and mode highlights reset.

Gaps open between the head and body

Enable Keep Seams Together, preview Find Seam Connections and confirm that corresponding seam vertices exist. Use a seam group when nearby unrelated boundaries could be linked. Rerun Wrap from the original neutral Template to replace an older gapped result. Different boundary vertex counts need manual preparation.

First point on a dense Target takes a moment

The first mirrored lookup prepares the Target surface. Later clicks reuse it; changing Target geometry requires a rebuild. Avoid changing modifiers or topology during placement.

Nudge is slow or follows the wrong overlapping surface

Use the current build and a smaller radius to reduce the affected area. If the initial attachment is wrong, correct the landmarks or restrict the Template part to its intended Target mesh, then restart Nudge. Disconnected Target surfaces cannot be crossed by one continuous attachment.

Point placement is rejected with Template modifiers

Topology-changing Template modifiers cannot safely map visible hits back to original vertex indices. Disable them or apply them on a copy before placing points. For collection Templates, also follow the neutral-state requirements above. Target modifiers are supported.

Wrap a full-body MetaHuman

Follow a complete full-body wrap using a MetaHuman with separate head and body meshes. Learn how to set up collections, place matching landmarks, keep the neck seam together and refine the result.

Watch the full-body tutorial on YouTube ↗

Support and questions

For support, bug reports or questions about BWrap, email victor@skalin.org. Messages go directly to me.