USoftSubdiv Reference Finder
============================

What it is for
--------------
A scene that comes back from another machine -- an animator, an archive, a copied
project -- opens with Maya asking where every rig went. This tool takes one folder,
finds those files under it, and repaths them in one pass.

Install
-------
Recommended: drag and drop
1. Extract USoftSubdiv-ReferenceFinder.zip into any folder. Do not drag a
   file out of a zip viewer without extracting first -- install.py needs
   the usoftpipeline folder next to it on disk, and a zip viewer does not
   put it there.
2. Drag install.py from that extracted folder into the Maya viewport.
3. A dialog reports what was installed and where. The Ref Finder shelf
   button (this tool) appears on a shelf tab named USoftSubdiv.

Re-running install.py, for example after unzipping a newer version, replaces
the existing install, so it doubles as the updater.

This tool has a separate, unrelated sibling -- the USoftSubdiv Alembic
exporter, which has nothing to do with reference repathing. It ships as its
own download, USoftSubdiv-MayaTools.zip, installed the same drag-and-drop
way. If you extract that archive's install.py next to this one's
usoftpipeline folder -- for instance because you unpacked both zips into the
same folder -- dragging either install.py installs both tools; each
installer only ever installs what it finds beside itself.

Fallback: manual install
If drag-and-drop is blocked in your setup, install by hand instead:
1. Copy the `usoftpipeline` folder into your Maya scripts folder, e.g.
   C:/Users/<you>/Documents/maya/scripts/
2. In Maya's Script Editor (Python tab), run:

       import usoftpipeline
       usoftpipeline.install_shelf()

   A "Refs" button appears on the USoftSubdiv shelf. Run it once; it is remembered.

Use
---
1. Open the scene. When Maya asks about a missing reference, press Skip for each
   one. (See "Which button" below.)
2. Press the "Refs" shelf button.
3. Set "Search folder" to the folder the rigs live in and press Search.
4. Check the list:
       OK        one file matched -- nothing to do
       ?         several files matched -- pick the right one from the list
                 The list starts on "-- pick one --". A row left on that is
                 skipped by Apply, so pick a file before you press Apply.
       MISSING   nothing matched -- press Browse... and point at the file
5. Press Apply. The references are repathed and loaded, and the list refreshes.
6. If new rows appear, press Apply again: a rig can carry its own references, and
   those only become visible once the rig itself is loaded.
7. Save the scene. The new paths are stored in it, so the next open is clean.

Which button
------------
Skip leaves the reference in the scene, unloaded, still pointing at the path that
does not exist -- which is exactly what this tool needs in order to fix it. Use Skip.

How it picks a file
-------------------
The filename must match exactly, and among files with that name the one whose folder
path agrees with the old path for the most steps wins. `scenes/_Characters/Bek/rig.mb`
beats `backup/rig.mb`. When two files agree equally well the tool does not guess -- the
row is marked `?` and you choose.

Notes
-----
- Textures and caches (file nodes, image planes) are not handled -- references only.
- Search looks for .ma, .mb, .fbx, .abc, and .obj files under the folder -- Maya
  references all five directly, not just its own .ma/.mb scene formats.
- The tool never deletes or moves a file. It only changes what the scene points at.
