Getting Started

Getting Started

A five-minute tour. By the end of it you will have packed several meshes onto one shared atlas and saved the project for later.

If you have not installed the app yet, see Installation.

What you need

• 3D geometry mesh objects in OBJ, FBX, glTF / glb, PLY, or STL format.
• One or more textures per mesh (PNG, JPG, TGA, BMP, EXR, or 16-bit PNG).
• A output folder where the app can write the output atlas and the meshes with modified UV.

UV Texture Repacker does not care where the files come from or which folder they live in — you can mix sources.

Step 1: Add your meshes

Meshes can be added using either the button or right click context menu.

Click + Mesh at the bottom of the Outliner panel on the left. A native file picker opens. Multi-select is fine; every selected mesh becomes its own mesh layer in the outliner.

Right click and select Add mesh or click the button

Each mesh appears as a mesh block (a rounded panel containing one mesh layer plus its texture-layer children). Beneath the mesh name you will see its triangle count, vertex count, UV-shell count, and bounding-box dimensions. If a mesh has no UVs, it shows a red "no UVs" stripe and will not be included in the pack.

A mesh block is the combination of a mesh layer and it's child texture layers. Any layer, mesh or texture selected, will highlight the entire block with a thin margin on the left.

Step 2: Add textures

Click a mesh layer to select it, then click + Texture at the bottom of the outliner. Pick the textures that go with that mesh. You can pick several at once, then drag and drop them to the correct mesh block.

You can also right click a mesh layer and select "Add Texture(s)..."

Right click menu are context aware

When textures are added, the app tries to guess each one's channel (Albedo, Normal, Roughness, etc.) from the filename — see Channel Types for the rules. The guessed channel appears as a coloured pill on the right of the texture layer. If the guess is wrong, click the pill and pick the correct channel from the dropdown.

By default the app considers two channels active: Albedo and Normal. If your textures use other channels (Roughness, Metallic, Emissive…), open the Active Texture Types dialog from the outliner header and add them. See Active Texture Types for the full walkthrough.

Step 3: Pick output settings

Look at the Controls and Pack strip at the bottom right. The defaults are sensible for most jobs:

• Resolution — the size of the packed atlas in pixels. Default 2048.
• Padding — pixels reserved between UV islands. Default scales with resolution.
• Dilation — how far each island bleeds outward to survive bilinear filtering and mip generation. Default 8.
• Filter — sampling filter when shells are scaled. Default Bilinear.
• Packer — Bitmap (default, fast, respects the resolution exactly) or xatlas.
• Output folder — the folder where the atlas image and rewritten meshes will be written. Set this before you pack.

If you are unsure, leave everything at default and just set the output folder. See Controls and Pack for what each control does in detail.

Step 4: Pack

Press the big Pack button. A progress bar runs across the bottom of the window. On a typical job this finishes in a few seconds. The status bar reports Pack complete in N s · utilization P% when it is done.

The app automatically switches the Preview panel to atlas view so you can see the result. Use the channel pill at the top right of the preview to flip between channels (Albedo, Normal, etc.).

In your output folder you now have:

• One or more atlas_<channel>.png (or .exr) images — the packed atlases.
• A copy of every input mesh, with its UV channel rewritten to point into the atlas.

These output meshes are drop-in replacements for the originals. Reimport them into your engine or DCC and assign the packed atlas as the material's texture.

Step 5: Save the project

Press Ctrl+S (or the disk icon in the title bar). Pick a location and name; the file gets a .muvp extension. This stores every mesh path, every texture path, every channel assignment, and every setting. It does not store the actual meshes or textures themselves — only the paths to them.

Reopening the .muvp later (Ctrl+O, or the recent-files menu) restores everything, including the most recent atlas view if those files are still on disk.

See Title Bar and Project Files for the full save / open / recent-files behaviour.

Where to go next

• Outliner — the full set of outliner features (search, multi-select, drag-drop, context menus).
• Preview — UV overlays, zoom and pan, atlas mesh filter.
• Channel Types — how filenames are mapped to channels and how to customise that.
• Concepts — what padding, dilation, packer choice, and rotation actually do.
• Preferences — every setting in the Preferences dialog.