Texture Atlas Tool for Maya

This is a texture atlas tool we created during the development of Prisoner 84. It allowed us to quickly and efficiently produce texture atlases for the 40+ levels that appeared in the game. We have decided to release it to the public for anybody out there who might be looking for a texture atlas solution for their project. It is on the fussy side, however, so we have also made the source code available in the hope that, if you find it useful, you might also wish to contribute by helping to improve it.

Downloads

mayaTextureAtlas.zip 1.0 (109.01 kB) - This zip contains the final release version of the TextureAtlas tool, which can be installed for Maya 2012 x64.


mayaTextureAtlas-src.zip 1.0 (19.83 MB) - This zip contains the complete source code for the TextureAtlas tool.

Prerequisites

Before doing anything you should first make sure you have the following redistributions installed on your system:-

Visual Studio x64 re-distributable
http://www.microsoft.com/downloads/en/details.aspx?FamilyID=bd512d9e-43c8-4655-81bf-9350143d5867

DirectX dlls
http://www.microsoft.com/downloads/en/details.aspx?FamilyID=3b170b25-abab-4bc3-ae91-50ceb6d8fa8d

Please note this plug-in is currently built ONLY for the 64-bit Windows version of Maya 2012. Hopefully in the future – or through community help – we can get this cross-platform, the way it should be!

Installation

1. Copy “hg_TextureAtlas2012x64.mll” into your Maya “plug-ins” folder. This can be in either your “C:\Users\*YOURUSERNAME*\Documents\Maya\plug-ins” folder, or in “C:\Program Files\Autodesk\Maya2012\bin\plug-ins” (or wherever your copy of Maya 2012 is installed).

2. Copy “nvatlas.exe” into your Maya “bin” folder. This is usually in “C:\Program Files\Autodesk\Maya2012\bin” (or wherever your copy of Maya 2012 is installed).

3. Open up Maya and go to “Window > Settings/Preferences > Plug-in Manager”. Provided steps 1 and 2 were completed without error, “hg_TextureAtlas2012x64.mll” will now appear in your list of available
plug-ins. Tick the box next to “Loaded” to enable it (and optionally tick the “Auto load” box so that the plug-in is automatically loaded each time you open Maya).

How it works

Our TextureAtlas tool has two methods of atlasing: “Standard Atlas” and “Prebake Atlas”.

The standard method atlases by texture; so if your scene contains 10 separate textures then those 10 textures will be added to your atlas regardless of how many times they are used in the scene, and regardless of how many meshes there are in the scene (meshes that share textures are each allocated the same UV offsets within the atlas). This method is perfect when your artwork is going to be lit in real-time and doesn’t require pre-baked lighting of any kind.

An example of a standard texture atlas from Prisoner 84…Standard texture atlas method

The prebake method atlases by mesh rather than by texture. For example, if you have a single texture applied to 10 separate meshes in your scene, 10 instances of that texture (along with the corresponding UV offsets of each of those meshes) will be created inside the atlas. This means all 10 textures can be pre-lit (or altered in some other way) within the texture atlas itself.

An example of a prebake texture atlas from Prisoner 84…Prebake texture atlas method

Commands / How to use it

The TextureAtlas tool is run via Maya’s command line–although we recommend that you save each command to your shelf. Commands are as follows:-

“TextureAtlas”
Creates a standard texture atlas of selected meshes only

“TextureAtlas -all”
Creates a standard texture atlas of all meshes in the scene

“TextureAtlas -prebake”
Creates a prebake texture atlas of selected meshes only

“TextureAtlas -prebake -all”
Creates a prebake texture atlas of all meshes in the scene

 

I’ve run it, but what now?

Once the texture atlasing process has completed successfully, you will find the following files in your project’s “textures” folder:-

atlasTexList.txt
This is a list of all textures that have been added to your atlas (together with their absolute paths).

level-atlas.tai
This is the Texture Atlas Index file; it lists all textures together with their new UV offsets within the atlas itself.

level-atlas0.tga, level-atlas1.tga, and so on
These are your new texture atlas files. They are automatically assigned to your existing materials in Maya. It is recommended, however, that you move these to a different folder and create a new material in your scene to assign them to. This will avoid overwriting existing texture atlas data if you run the TextureAtlas tool again in the same Maya project.

Known Issues, Limitations and Workarounds

This tool is still very much a work in progress, so there are a few issues. However, most of these issues are avoidable if you follow the steps outlined in this section.

1. TEXTURES/UVS OVERLAP

Sometimes multiple texture UVs are allocated coordinates which cause them to overlap with one another inside the texture atlas.

This issue is usually caused by one of two things: 1) when rectangular textures–particularly those with a significant difference between width and height (i.e. 16×256)–are allocated atlas space near to a square texture, or 2) when the atlas tool is attempting to use up “odd space” caused by inconsistent texture sizes, non-power of two textures, or poorly grouped texture UVs.

Workarounds…

a) Avoid elongated rectangular textures
Use rectangular textures sparingly, and avoid using elongated rectangular textures (i.e. textures that are 16×256).

b) Use consistent texture sizes
To avoid “odd space” try to be consistent with texture sizes. This is the case regardless of whether or not you are using power of two textures (i.e. 16, 32, 64, 128, 256, 512, etc.).

For best results use square power of two textures as much as possible (the texture atlas is a power of two texture, so it makes sense that power of two textures will fit the best inside it).

c) Change scene hierarchy to control atlas output
Another trick to avoid “odd space” is to manually control where a mesh’s texture will appear inside the atlas.

The order in which a mesh is atlased is determined by its position in the scene hierarchy–a mesh that comes first in the scene will be dealt with first by the atlasing tool and will be placed in the top left corner of the file. To edit the scene hierarchy, open Maya’s outliner (“Window > Outliner”) and make sure “Display > Sort Order” is set to “Scene Hierarchy”. Now re-order your meshes in the outliner so that they are grouped by their texture sizes: meshes which have larger textures should appear first in the scene (when the texture atlas has more space to work with) and meshes which have smaller textures should appear last (when the texture atlas has less space available).

2) MATERIALS SEEM BROKEN WHEN MULTIPLE TEXTURE ATLASES ARE CREATED

When more than one texture atlas is created, Maya will automatically assign the last atlas file created to all of your existing materials. To avoid this we recommend limiting atlas usage to one per scene/level. It is, however, possible to manually re-assign separate texture atlas materials to the relevant meshes.

3) MESHES CAN ONLY HAVE ONE TEXTURE ASSIGNED (PREBAKE METHOD ONLY)

When using the prebake method, make sure multiple textures aren’t assigned to a single mesh, otherwise the atlas will get stuck in a loop. Individual meshes can only have one texture assigned to them.

4) A TIP TO SAVE SPACE (PREBAKE METHOD ONLY)

If you want to save space in your texture atlas, you can combine meshes that share a single texture and only one texture will be added to the atlas.

This is useful if you know two meshes that share the same texture are going to be lit in the same way (e.g. a symmetrical corridor), or if an object or tile appears in a level multiple times but doesn’t require a unique instance of its assigned texture (e.g. a door sign used throughout the level that doesn’t require lighting to ensure it is always legible).

Code

What you’ll need…

  • Visual Studio 2010 (any version should do-–even Express)
  • Maya 64 bit headers and libraries (the headers and libraries are part of a Maya install)

To compile the code you will need a version of Visual Studio 2010 with 64 bit compilation tools and the 64 bit versions of the Maya libraries. It is possible to build the 32 bit versions of everything if you wanted to, you just need to add the new target and make sure to link against the Maya 32 bit libraries.

You will have to set up the header and library paths for your Maya install into the project settings (you can just replace the defaults I’ve left in the project).

That’s pretty much all there is to change to get it compiling so long as the folder structure stays as it was in the zip file. The final mll files go into the ‘mll’ folder and should be copied to your document Maya path as you do each build, or you can tell visual studio to just place it there by default (be aware you can’t have the plug-in running in Maya when you compile this way as the file will be locked).

NVidia Texture Tool

The original code can be picked up here…
http://developer.nvidia.com/legacy-texture-tools

What you’ll need…

To compile the version supplied in the zip, you just need the latest DirectX SDK (I used the June 2010 as of writing). Again you need to make sure the headers and libraries are set up for the project to see them.

Changes to the original code…

I changed some of the code to force certain options that were very iPhone build specific. For example, the output atlas will always be a TGA regardless of the source textures, and it will create square 1024×1024 files without mipmaps.

The options in the nvatlas tool should really go into some sort of dialogue in Maya so you can pick and choose what you want. There are some parts of the code that are slightly broken by my changes. For example the important part of placing the textures into an atlas is not quite as precise as it used to be because I stopped it ordering textures by size.

Future plans

The codebase could do with a thorough clean-up; as is always the case it was created quickly for a specific purpose, and it never really went through a proper design phase, nor was it tested properly.

Below are a few things I believe should be done to get this tool nearer to what it should be in terms of functionality:-

  • The plug-in should not be reliant on the nVidia tool as this is preventing the tool from being cross-platform. It is also an inefficient way to implement such a tool. Using the rectangle bin packing code here http://clb.demon.fi/projects/rectangle-bin-packing is a very viable alternate which we are considering.
  • An “Undo” feature that fully supports Maya’s command history, so that an atlas can be generated at any time to check progress.
  • Better texture support (resolutions, bit types, formats, etc.)
  • Add a dialogue-based interface that can be used to customise atlas output as well as provide a convenient place to implement future additions to the available options.
  • More flexibility with Maya’s HyperShade system (i.e. it shouldn’t matter how everything was originally mapped and what materials were used)

Disclaimer

This tool is released as is. Please use at your own risk!