uvAutoRatio Pro
v2.3.1
www.uvAutoRatio.com







www.RenderHeads.com

Last Updated 22 October 2008

Contents


1. Introduction
1.1 What Is This?
 1.2 Key Features
2. Getting Started
2.1 Requirements
 2.2 Installation
2.3 Launching the Plugin
 2.4 Licensing
3. Quickstart
4. The User Interface
4.1 UVAutoRatio Tab
4.1.1 Main Controls
 4.1.2 UV Shell Finder Tool
 4.1.3 UV Shell Selection Tool
 4.1.4 UV Tools
4.2 Settings Tab
 4.3 About Tab
5. Other
5.1 Tips
5.2 Known Issues
5.3 Scripting
6. Usage Examples
6.1 Example 1
 6.2 Example 2
7. Release Notes
 8. Support


1. Introduction

1.1 What Is This?

UVAutoRatio 2.0 Pro is a tool to help Maya artists get their UVs (texture coordinates) to the right scale.   It unifies the '2D texture area' to '3D surface area' ratio across multiple meshes or mesh regions (UV shells).

This sounds rather complex, but really it's simple:

By scaling an objects UVs, its 2D texture area is scale relative to it's 3D surface area.  So objects with large 3D surface area will get a large texture area, and objects with a small 3D surface area will get a smaller texture area.

UVAutoRatio does this all automatically for you.  It is very fast and can quickly process scenes with a multitude of meshes or very high polygon meshes.  It also offers a host of options for customising the way operation are performed. 


1.2 Key Features

2. Getting Started

2.1 Requirements

The following versions of Maya are supported:

Microsoft Windows:

Apple Mac OS X:
Linux:

Please let us know about your platform requirements.

2.2 Installation

2.2.1 Windows Installation

UVAutoRatio 2.0 Pro is downloaded as an executable installer file.
  1. Once the file has downloaded, double-click the installer to launch it.
  2. The first screen asks you to select the folder that you would like the plugin to be installed to on your system.
  3. On the second screen you must select a folder on your machine where Maya is installed.  This will usually be something like "C:\Program Files\Autodesk\Maya2008".  If you have multiple versions of Maya installed, you need to run the installer again for each version you want to use the plugin in and select the appropriate path each time.
  4. Now you can click 'Install', and after a few seconds the plugin will be installed.
  5. Launch Maya.


2.2.2 Windows Uninstalling

Simply run the uninstaller from the Start Menu in "RenderHeads , UVAutoRatio 2.0 Pro".


2.2.3 Linux Installation

  1. Decompress the archive to the directory where you want the plugin to live.  This should be somewhere like "~/UVAutoRatio 2.0 Pro".
  2. Open the file UVAutoRatioProModule.txt, and edit the path at the bottom to be the folder where you've put this plugin in step 1.
  3. Copy UVAutoRatioProModule.txt into the "modules" folder of Maya, which is usually found in:

          /usr/autodesk/maya2008

    (The folder may need to be created if it doesn't already exist)

  4. Launch Maya


2.2.4 Linux Uninstalling

Simply delete the folder containing the plugin, and remove the UVAutoRatioProModule.txt from your Maya/modules folder.


2.2.5 Mac Installation

  1. Decompress the archive to the directory where you want the plugin to live.  This should be somewhere like "/Applications/UVAutoRatioPro/".
  2. Open the file UVAutoRatioProModule.txt, and edit the path at the bottom to be the folder where you've put this plugin in step 1.
  3. Copy UVAutoRatioProModule.txt into the "modules" folder of Maya, which is usually found in:

          /Applications/Autodesk/maya2008/maya.app/Contents/modules/

    (The folder may need to be created if it doesn't already exist)
    (To open maya.app, go the the gear icon in Finder and click "Show Package Contents")
  4. Launch Maya.


2.2.6 Mac Uninstalling

Simply delete the folder containing the plugin, and remove the UVAutoRatioProModule.txt from your maya.app/Contents/modules folder.


2.3 Launching the Plugin


To launch the plugin type "UVAutoRatioProUI" into the command-line window in Maya.  This will display the UVAutoRatio window.



To save typing you may want to add this command to your shelf.  The user interface has a button in the settings tab labelled "Add to Shelf" which will add this command to the current shelf using it's own icon graphic.


The button icon added to the shelf:


2.4 Licensing

UVAutoRatio Pro won't work until it has been given a valid license key.

To obtain and install a license key:

  1. Go to the "About" tab and click "Enter New Key", this will bring up the licensing window:

         
        














  2. If you don't already have a license key, you can either click "Get 15-Day Free Trial Key" which will take you to the website where you can claim your free trial key or "Purchase Key" to launch the license shop website.
  3. Once you have a key, paste it into the box below.  You can use CTRL-V to paste it since right-click doesn't work in this Maya text box.
  4. Click 'OK'.

Your copy of UVAutoRatio will then be licensed, as indicated by this window:

If this doesn't appear and you're having problems getting your license to work, please contact RenderHeads Support (support@renderheads.com).

3. QuickStart

The plugin launches with the most important controls visible:


Unifying Texture Ratio Across Multiple Objects

  1. Select the meshes you want to process.
  2. Click 'Apply to Objects'.


Unifying Texture Ratio Between Multiple Shells

  1. Select the shells you want to process so they have the same ratio.
  2. Click 'Apply to Shells'.


Matching the Texture Ratio of Multiple Objects to the Texture Ratio of a Specific Object

  1. Select the object that has the desired texture ratio.
  2. Click 'Set Ratio from Selection'.
  3. Select the objects (or at least one component in each object) you want to change.
  4. Click 'Apply to Objects'.


Matching the Texture Ratio of Multiple UV Shells to the Texture Ratio of a Specific UV Shell

  1. Select the UV shell that has the desired texture ratio.
  2. Click 'Set Ratio from Selection'.
  3. Select the UV shells (or at least one component in each shell) you want to change.
  4. Click 'Apply to Shells'.



4. The User Interface

The user interface is divided into 3 tabbed sections:


4.1 UVAutoRatio Tab

4.1.1 Main Controls - Where the action happens


This is the most important panel in the whole interface as it contains the buttons: 'Apply to Objects' and 'Apply to Shells'.  These are the two operations that the plugin performs.

Running either of these operations will result in the UVs of the selection being scaled (and perhaps translated to fix overlapping UV shells if that option is selected).

The UVs are scaled so the ratio between the selected 3D area and it's 2D texture area matches (or at least comes extremely close to) the ratio specified in the box 'Current Ratio'.

'Apply to Objects' will scale the UVs of each selected object (polygon mesh).   Whole objects don't have to be selected for this to work - if the selection is made up of components of an object (vertices, edges, UVs, faces, etc) it will still operate on the entire object.

'Apply to Shells' will scale the UVs of the selected UV shells so they have the desired ratio.  If the selection just contains components (vertices, edges, UVs, faces, etc) the UV shell that contains them will be processed.  If an object is selected then all of it's UV shells will be processed.

The value in 'Current Ratio' can be manually edited, or it can be set to the ratio of the current selection by clicking 'Set Ratio from Selection'.  This will work with any selection, from a bunch of polygon meshes to a single face.  This can be very useful in making other objects/shells match the ratio of another object/shell/selection.

4.1.2 UV Shell Finder Tool - Lists UV shells in the selection
    
This is a handy tool that displays each UV shell in the selection and then allows you to select the shells simply by selecting items in the list.

Multiple selection is supported, and each UV shell you select in the list will be added to the current selection.

Double clicking on an item in the list will zoom the camera to that UV shell (just like the hotkey 'F' in Maya).

This tool can be used to easily select UV shells for capturing the ratio of that shell using 'Set Ratio from Selection', or it can be used as an easy way to build up a selection of shells to be processed.
4.1.3 UV Shell Selection Tool
Ticking this checkbox will make any component selection automatically propagate the selection to that entire UV shell.

4.1.4 UV Tools - Handy shortcuts

This panel is a collection of shortcuts to tools (most of them internal Maya ones) commonly used in conjunction with UVAutoRatio, placed here for quick and easy access.

Left clicking will apply the tool.  Tools with options will display a small icon next to the cursor when hovered over, indicating that it can be right-clicked to bring up the tool options.
Right-clicking on these tool buttons will open up their options window.

Ratio Inspector

Ratio Inspector is the only non-Maya tool.  This handy tool opens up in a new window and will show you the surface and texture area of anything as you select it.  It also shows you the ratio between the two areas.


4.2 Settings Tab

4.2.1 UV Set Settings - Specifying which UV set to operate on


By default the UVAutoRatio Pro will operate on the 'current' UV Set of a mesh.  These settings allow you to specify alternative UV Sets to operate on.

The current UV Set in Maya is a per-mesh property and can be set in the texture editor.  Since the current UV Set can vary between meshes it can be useful to force the plugin to a UV Set of a specific name.

To manually specify the UV set to use:

  1. Select the 'Manually select UV Set' radio button.
  2. Select the mesh that has the desired UV Set.
  3. Click 'Update UV Set List from Selection' to fill the box with the list of UV Sets the mesh contains.
  4. Now select the desired UV Set from the list.

If you do manually specify the UV Set, you can also define what happens when the plugin encounters a mesh without the named UV Set.  The mesh can either be skipped or processed using it's current UV Set.  If any meshes are skipped, a warning will be logged to the script editor window showing which meshes were not processed.

4.2.2 Display Options


These display options apply to the UV Shell Finder Tool.  When selecting UV shells from the list they can either be displayed as UVs or faces.

4.2.3 Layout Options - Automatically fixes overlapping UV shells



When UV shells are scaled up they can sometimes overlap each other.  This option decides what the plugin does about this. 

The 'Move shells to fix overlaps' option does what it says.  This is similar to the option in Maya's 'UV Layout' command, however instead of completely rearranging the UV shells it will preserve the original layout of the shells relative to each other.  Even if the shells already have the desired ratio, having this option on will fix overlapping shells.

The images below show UV shells that are overlapping, and the automatically fixed result:































Before - shells are overlapping

After - Overlapping fixed while maintaining the original layout

4.2.4 Misc Options


Scaling Axis:
Usually the UVAutoRatio 2.0 Pro will scale the object/shell equally in both horizontal and vertical directions to find the scale which gives the desired ratio.  These options allow you to limit the scaling to either the horizontal or vertical axis. 

Logging Verbosity:
If "Verbose Output" is enabled the plugin will write detailed information into the script editor output window about it's internal operations.  This might be interesting/useful to advanced users.  Here is an example of the data it displays:



Save Settings:
By default the plugin will remember the last used settings and will restore them when you use the plugin in future.  This can be disabled by checking this "Reset Settings on Startup" option.

Shelf:
The "Add To Shelf" button will add a shortcut to the MEL command "UVAutoRatioProUI;" to the current shelf.

Reset Settings:
Finally the settings can all be returned this their default state by pressing this button.


4.3 About Tab

The About tab is pretty straightforward:

The license panel displays the details of the currently installed license.  It also allows new keys to be entered and the 'Purchase Key' button will launch the RenderHeads Store in the default web browser.
The plugin panel displays information about the plugin.  This is very useful for troubleshooting.  When reporting a problem, please include this data in your query.

Finally there are some links to web pages related to this plugin.  This is useful for checking for updates and bugfixes.  The User Group is an online community where users can post their opinions and queries, make feature requests, show off what they've used the plugin for, get access to upcoming beta versions and interact with the developers directly.


5. Other


5.1 Tips

Clearing history will improve the performance of the plugin


5.2 Known Issues

5.2.1 "Can't perform polyMoveUV on Selection"

There have been reports of some models that don't work with the plugin, and output:

// Warning: line 1: Can't perform polyMoveUV1 on selection //

We have tracked this down to a bug in Maya where it has an invalid current uvset assigned to the mesh.  To fix it, simply select the mesh, open the Texture Editor window, go to the UVSet menu and select the UV set (even if it's already selected).


5.3 Scripting

It is also possible script UVAutoRatio Pro to include it into a workflow or custom pipeline.  Below is a list of the commands that come with UVAutoRatio Pro and descriptions of their parameters.


5.3.1 GetSurfaceUVArea Command

This command uses the current selection and returns 3 floats: the 3d surface area, the 2d texture area, the ratio of surface area / texture area.  Its parameters are:

Short name
 		Long name
 		Value type
 		Description
-us
 -uvSetName
 string
 The name of the UV set to use (optional)
-fb
 -fallback
If the named UV set is not found in a mesh, use the default UV set instead of skipping it (optional
-hlp
 -help
Displays this parameter list


5.3.2 UVAutoRatioPro Command

This is the main command which does the UV scaling and UV shell manipulation.  Its parameters are:

Short name
 		Long name
 		Value type
 		Description
-hlp
 -help
Displays this parameter list
-r
 -ratio
 float
 Desired 3D : 2D ratio
-us
 -uvSetName
 string
 The name of the UV set to use (optional)
-fb
 -fallback
If the named UV set is not found in a mesh, use the default UV set instead of skipping it (optional)
-op
 -operation
 integer
 0 = whole mesh, 1 = uv shell
-vb
 -verbose
Display output (optional), default false
-lay
 -layout
Layout UV shells to prevent overlapping (optional), default true
-ss
 -skipscale
Skip the scaling operation (useful if you only want to fix layout) (optional)
-osh
 -onlyScaleH
Restrict scaling of UVs to horizontal axis (optional), default false
-osv
 -onlyScaleV
Restrict scaling of UVs to vertical axis (optional), default false


6. Usage Examples


6.1 Example 1

Lets say we have 4 'rocks' all different scales and using the same texture, looking something like this:

We can see that the large 'rock' is using the same amount of texture area as all the other smaller 'rocks'.  But we'd really like the texture usage to be proportional to the area of the mesh.  Here are some reasons why:

  1. We want the features in the texture to be the same size across the rocks.  A crack or a grain shouldn't really scale if they're made of the same material.
  2. It is a waste of processing power to have small objects using disproportionately large regions of the texture when they don't need to.

So we'll run UVAutoRatio to unify the UV ratio across multiple objects, producing this result:



6.2 Example 2

You've finally finished unwrapping/pelting your UV shells and you have something like this:
Now you have to manually inspect each shell and try to guess what size to scale it so they're all proportional.   This is a serious drag!  You want to do this for a few reasons though:

  1. You want to divide up your texture in proportion to how much of it will be seen in the 3D world, otherwise it's a waste.  The less texture waste there is, the more pixels you can dedicate to the details.
  2. If it's a character you might want to give the head/face double the resolution compared to the other parts.

Instead let UVAutoRatio do it for you:

7. Release Notes


Version 2.x - ?



Version 2.3.1 - 22 October 2008


Version 2.3 - 11 September 2008


Version 2.2.1 - 15 August 2008



Version 2.2 - 24 June 2008



Version 2.1 - 24 April 2008



There is now a new option to automatically hide and then reshow the texture editor window while the plugin is doing it's work.  This makes the plugin work a lot faster for high polygon meshes.


We've increased the speed of the case where your meshes has overlapping UV shells, and you use the option to automatically fix overlapping shells.  This now takes half the time.


Added a progress window.  This is useful for high polygons meshes that may take some time, gives reassurance that the Maya hasn't frozen.


The plugin can now be interrupted.  So if you made a mistake and told it to do some horrendous amount of work you can just hit the escape key and it'll stop.


A new button to just run "fix overlapping UV shells".

Pressing the UV Texture button when the window is open will now hide the window.  The same goes for the Ratio Inspector.

The licensing changed slightly, so you may need to re-enter your key again.


Version 2.0 - 2 April 2008



8. Support


Website


UVAutoRatio has it's own website where updates and news can be found:


http://www.uvAutoRatio.com



UVAutoRatio Discussion Forum


Use the discussion forum to post your questions, opinions, submit feature requests, report bugs and show off ways you've used the plugin:


http://www.RenderHeads.com/forum/viewforum.php?f=4



RenderHeads Details


For further support please contact the developers directly:


Web: www.renderheads.com

Email: contact@renderheads.com

Phone: +447970692070