====== Maya to Indigo ======

Revision 172 - 2 Dec 2007

Documentation Version 0.1.6 - 2 Dec 2007




==== Where to get the exporter ====

The latest "stable" release of the exporter can be found as an attachment to a thread in the Maya forum:

[[http://www.indigorenderer.com/joomla/forum/viewforum.php?f=11]]

If you wish to live on the cutting edge, wish to help test the latest developments, and are willing to put up with some possibly broken features, you can obtain the very latest code from the following SVN repository:

  https://svn.hamsterfight.co.uk/svn-mti/trunk/

Please consult google for information on how to "check out" code from this source.

**Using the latest development code is not recommended for serious work. It may break your scenes.**

==== Installation ====

Copy the MayaToIndigo folder to

''%userprofile%\My Documents\maya\<your Maya version>\scripts''

Copy the contents of the CopyTo_XXXX folders to the appropriate locations.

Copy the contents of the Icons folder to

''%userprofile%\My Documents\maya\<your Maya version>\prefs\icons''

Place the following in

''%userprofile%\My Documents\maya\<your Maya version>\Maya.env''

  MyPath = %USERPROFILE%\My Documents\maya\<your maya version>
  MyScriptPath = %MyPath%\scripts
  MAYA_SCRIPT_PATH = %MyScriptPath%\MayaToIndigo

where ''<your maya version>'' may be 8.0/8.5/2008 etc.
(btw, windows understands ''%userprofile%'' - run it from the start menu ;).

You can also add these folders to system path variables instead, if you are used that way.


==== How do I start it? ====

To run the exporters interface type the following command:
''mti_Main;''
You will see a small window with a menu bar, some tool buttons, and a load of different options.

===== The Exporter Window =====

==== The menus ====
Theres not much in the menus. This is intentional in order to keep the exporters functions mostly visible.





=== The buttons ===
== The first row of buttons ==
1.	Create indigo camera. You will need one in your scene.

2.	Create Sun. This adds a directional light which will be exported as indigos sun. After adding the sun, you will need to enable it for rendering before you export. The sun points towards its locator (its constrained) so the sun angle can be set easily. Remember that only the angle is important, not its location.

3.	Create IES Locator.

4.	Create Exit Portal. This adds an object to your scene that is correctly named to be exported as an Exit Portal. Normals have to point "inwards", e.g. into a room. 

5.	Make Instances.

6.	Convert all NURBS to Polygons. Only polygons get exported, so youll need this if some of your objects are NURBS. 

7.	Reverse face normals. Important to make lights, Exit Portals and SSS-materials behave correctly. Lights and  Exit Portals should face towards the scene.

8.	Delete all history. A lot of the time this isnt necessary, but it can sometimes fix certain objects that fail to export.

== The second row ==
1.	Hypershade.

2.	Turn smooth shading off.

3.	Turn smooth shading on.

4.	Toggle face normals visibility.

5.	Toggle backfaces visibility.

6.	Triangulate Polygons.

7.	ToggleUndo.

8.	Flush Undo Cache

More on their respective functions below.


=== Scene Preparation ===
This section is primarily for adding some of Indigos material properties to Mayas shaders. Nk_data is only available on Phong shaders.

You should first select the shader you want to add these attributes to, check the boxes of the attributes you want to add, and click the Add button. Trying to add these attributes to your geometry or anything else will not work.

The cameras F-Stop and autofocus settings also live here, as well as the environment lighting options.


=== Render Settings ===
Here you have access to Indigos main render settings, including the render resolution and the save options.

The Edit settings button takes you to the mti_settings scriptnode. More on this later.


=== Writing to file ===
These options control which parts of your scene will get exported, and where.

SaveXML:	Saves the scene to an XML file for indigo.

SaveObjs:	Saves your objects to .obj files in the mti_objsSavDir folder. Uncheck it when you edited something that was not a geometry for instant export.

Instances:	Exports your object instances.

Local:		Exports your scene to the mti_indigoLocalDir rather than in your mti_indigoDir.

Append:		Exports only additional .obj files that have been created since the last export.


=== Rendering ===
These options control what to do once the scene has been exported.

Console:		Runs the console version of indigo rather than the full GUI.

RenderDirect:		Launches Indigo once the export process has finished.

NetWMaster:		Runs Indigo as a Working Network Master.

The final setting is the network port that Indigo will serve on.


=== Generate XML Code ===
This button makes all kinds of magic things happen (ie. it starts the export process ;) )



===== The Script Node =====

This is a special place where all of the exporters settings are held. The script node is named mti_settings. It is created when you first run the exporter, and will stay with your scene when you save it. The first thing you will need to do for each scene is set your paths.
mti_indigoDir should be the path to where indigo.exe resides. Use forward slashes instead of backslashes and also put a forward slash on the end. Eg:

''U:/render/indigo/indigo_v1.0.3/''

mti_indigoLocalDir is where you want the XML files to be saved. Eg:

''U:/render/indigo/scenes/''

The objs, textures, IES and environments paths should be entered as paths relative to the scene file. The exporter will output the scenes objects in the mti_objsSavDir folder. You will have to copy over your IES and environments yourself. The textures and objs folders will be created automatically in the same place as the xml save directory.

Once you have set your defaults, you can save your settings as a Preset so that setting up the next scene isnt such an effort.

A lot of the settings on the exporter GUI are linked to the values in the script node. The script node contains many more settings than the GUI, allowing full control of Indigo.
This is the place to enable Sunlight if you created a Sun with the GUI, for example.

===== Shaders and Materials =====

Because Maya and Indigo dont use the same materials, some translation has to happen. Some of Mayas shader types are exported as Indigo materials, and others are ignored.


=== Meshlights ===
Although not technically materials in Indigo, all you need to do to turn any mesh into a meshlight is set up the Incandescence and glowIntensity attributes on any of Mayas shaders that supports Incandescence.
The values are translated as:

  glowIntensity	-> Power Drawn

For R > 1000: Blackbody spectrum
  R	->	Blackbody Temperature (deg K)
  G	->	Gain

For 250 < R < 1000: Peak spectrum
  R	->	peak_min
  G	->	peak_width
  B	->	base_value
  (peak value = 1)

for R < 250: RGB spectrum; use RGB as normal.

  WARNING: Meshlight <overall_luminous_efficacy> is currently fixed at 2.0



IES data can be used by adding the mti_ies custom attribute.



=== Phong -> Phong ===
The simplest translation is Mayas Phong shader. This gets exported as an Indigo Phong material.
Values:

  Color (RGB)				->	diffuse_albedo_spectrum
  Cosine Power		->	x100	->	exponent
  Refractive Index			->	IOR

Attach file textures to color for albedo texturing. Attach file texture to cosine power for exponent maps. Use bump maps as you would in Maya, use the bumpDepth control to alter the bump amount.

If the shader has any of the following custom attributes they will be enabled:

  mti_nkdata		->	nk data file
  mti_ies			->	IES light file



=== Lambert  -> Diffuse(_transmitter) ===
  Color (RGB)		->	albedo_spectrum

If Transparency is not black, then the material becomes a diffuse transmitter. This will also disable bump_map.

Attach file textures to color for albedo texturing. Use bump maps as you would in Maya, use the bumpDepth control to alter the bump amount.

If the shader has any of the following custom attributes they will be enabled:

  mti_ies			->	IES light file


=== Blinn -> Specular ===

  Color (RGB)		->	absorption_coefficient_spectrum
  Refractive Index	->	IOR
  Surface Thickness	->	cauchy_b_coefficient
  Refraction Limit	->	precendence
  Translucence Focus	->	henyey_greenstein g_spectrum uniform value
  Ambient Color (RGB)	->	RGB scattering_coefficient_spectrum

Either uniform or RGB scattering_coefficient_spectrum can be used. If ambient color = black, then the following applies

  Light Absorbance	->	Uniform scattering_coefficient_spectrum

If Light absorbance  = 0, SSS will be disabled.

Attach file textures to color for albedo texturing. Use bump maps as you would in Maya, use the bumpDepth control to alter the bump amount.


=== LayeredShader -> Blend material ===

In order to achieve an Indigo blend material, you need to use a LayeredShader with exactly two other shader inputs. The final blend_factor will be the transparency of the first shader multiplied by the transparency of the second. These transparency values may come either directly from the layered shader is there ar no incoming connections, or from the input shaders if they are connected. The R, G and B components of transparency are averaged to find the final blend_factor.

To use a blend map, attach a file texture to the transparency attribute of the first shader, and link transparency through to the layered shader.

See the picture below for some texturing and blend examples.

> note that checker below is a file texture.
{{http://www.indigorenderer.com/joomla/forum/files/v2shaders_320.png}}


=== PhongE -> Direct material specification ===
Using the Notes field, the XML for any pre-made Indigo material can be exported directly. Some values can be substituted at export time.

Refer to the presets for working examples.

To allow protoyping of shaders and still export a working XML-Scene, the Comment has to be started with the exact text:

  <!-- mti_UseCommentAsMaterial -->

If that text signifies that the comment should be exported, it is directly written as a matieral statement. To simplify adressing materials by the correct name and to be able to access them via the Maya-Interface, following keywords can be entered and will be replaced by the value associated with the keyword:

  mtiKey_ShaderName    	-> the correct material shader name				-> phongE1SG
  mtiKey_ShaderColour   	-> The RGB-value of the phongE, would result in e.g.  		-> 255 0 0
  mtiKey_ShaderColAmb	-> The ambient Colour of the phongE, would result in e.g.  	-> 255 0 0
  mtiKey_GlobalGamma	-> Derived from mti_settings, 	-> 2.2 - compensates linear to exponential exposure
  mtiKey_Exponent		-> Some phongE value, intended to pass an arbitrary float value
  mtiKey_ior		-> Refractive Index of phongE


=== We currently lack direct support for ===

  *  glossy_transparent
  *  medium::epidermis
  *  medium::dermis
  *  rectanglelight
  *  plane
  *  sphere

===== Instances: =====
==== Overview ====
Instancing an object adds new representation of that object in the scene, without extra memory load. in a MtI scene instances are represented by special locators, called mtiInstanceLocator* by default. 
==== Usage ====
The creation of these locators has been automatized to a certain point; Your instancing tool has no name and hides behind the icon representing a cube and 4 locators. Selecting meshes and locators, or not, assigns different tasks to the script, other types of objects are ignored if selected.




=== The basic locator ===

  *  deselect all in scene,
  *  click the icon.

A single locator is created. Take notice that it has extra attributes in it's transform node, where informations relative to the instance are stored. These attributes are the following:

== Mti_ObjsToInstanceShape ==
The name of the shape to instance.
Due to the creation method its field is currently empty. One method is to manually type the meshe's shape name in.
== Mti_UseExactName ==
Not Documented. May affect how locators are recognized by the exporter.
== UpRotationRandomRange ==
Amount of fuzzyness in the vertical angle rotation, in degrees.

== Notes ==
  -  You can press the button multiple times without having to deselect everything between each click.
  -  Once created and feeded with the object's name, the locator can be duplicated, moved, rotated and scaled at will. Scale is considered as a single factor in Indigo though, only the scale X is read by the exporter. As a consequence it is advised to scale them uniformly.
  -  Do not Freeze Transformations ! If locators are too smal to be manipulated in your scene at creation, scale them right prior to any placement, then Freeze Transforms, then finally place them as needed.


=== Direct Method ===

  *  Select a mesh, click the icon.
The new locator is ready to instance the selected mesh.
== Notes ==
  -  You can select as many meshes as you want, every one of them will have it's related locator created.
  -  Your selection must be of polygonal meshes only, ie if a nurbs object is also selected nothing will happen.


=== Indirect Method ===

You don't have to start with MtI locators, Maya's default locators can be used as well (menu: Create > Locator).

  *  Arrange simple locators in your scene where you want the instances of an object to be,
  *  select the locators and the original mesh together and click the icon.

== Notes: ==

  - you can select, by mistake or convenience, any kind of object before calling mti_makeInstances. If they are not mesh nor locator they will just be ignored.
  - If more than one mesh is selected, all but first will be ignored as well. First mesh in selection list is used as original to instance.
  - Previously created mtiInstanceLocator can be updated with a new mesh name by the same procedure.
  - Locators used as IES placement should be preserved.

===== Other helper functions =====


=== mti_makeIESLight; ===
This creates a very small plane, parented to a locator for easy manipulation. Intended to be used as the mesh for an IES light. The planes normal points down (-Y).
As of MtI 0.9 it also creates the necessary shader, called IESShader and adds the custom mti_ies sttribute to it.