User documentation for the sPolyReduce maya plugin.


Installation

As with most maya plugins, two files will need to be installed for the plugin to work. There are two versions of the plugin provided, both very similar in behaviour. One version (version 2) is slightly more faster, but seems to produce objects of slighty less quality, due to the short testing period for this newer version. I therefor recommend version 1 to be used. Both versions contain the same files, namely the sPolyReduce.so file and a mel template called AEsPolyReduceTemplate.mel . The .so file is to be placed in the $HOME/maya/plug-ins directory, and the mel template in the $HOME/maya/scripts directory. The install script provided in both the version1 and version2 directory will try and put these files in the appropiate place automatically.

Upon loading maya, the plugin should be available for manual loading from the settings/preferences->plugin manager. Please see the maya documentation if you are still unsure about how to load plugins.


Initialisation

Once the plugin is loaded, the user is just a few steps away from using the tool. The tool can be created by typing in sPolyReduce in the script editor. For the tool to work, a camera and and a polygonal object must be selected. Depending on where the camera is in relation to the object, a reduction will be calculated instantly using the default settings. It is recommended not to use meshes of more then a few thousand edges for testing purposes, due to the speed of the algorithm. (See the report for more details) Most of the testing I have done has been on a default maya polygonal sphere. With only 780 edges, it takes a few seconds to compute. If the tool has been initialised succesfully, both the camera and and the mesh object will have the same sPolyReduce node attached to them. Selecting the camera, should turn the mesh object purple (in wireframe mode) as to indicate the camera affects it's appearance.


Static reduction attributes.

In the attribute edtior of the sPolyReduce node the first section available is the static reduction attributes. A quick description of what each attribute affects.


Force Reduction

The default value is off, which will let the camera position deside how much an object should be reduced. Turning this setting on will force the reduction value provided in the extra attributes tab to be used, and as such the tool will behave more like a traditional polygon reduction algorithm. All other options in the static reduction attributes will consequently have no affect, apart from the reposition button.


Reposition

The default value is on, which means the algorithm will try and find a better location for the new vertex after an edge collapse. When this value is set to off, the new vertex will always be in the center of the collapsed edge, thus reducing visual quality of the model in most cases. However, the speed of the algorithm is slightly improved by not having to reposition each vertex.


Maximum

The default value is set to 10, which means the maximum reduction performed by the algorithm is 10%. This amount of reduction is applied whenever the object is far away or out of view. 10 is a very conservative setting and generally a higher value would be required. Valid range is between 0% and 100% reduction.


Near Cam Distance

This refers to a safety area around the camera, especially usefull when used with a ray trace render. This value, default 10, provides us with a spherical area around the camera, though this value is only used when the object is not in view. It provides the user with an option to have a smooth transition in level of detail from where the object is reduced at maximum value and the object being in view. An example for it's use would be an object moving from behind the camera into view.


Far threshold

This is a value which refers to a distance from the camera. When the object is in view, but further away then this distance, maximum reduction is applied. The default value is 100 units, but any positive value could be used.


Near threshold

Like the far threshold value, this is another distance from the camera. If the object is in view and closer to the camera then this value, no reduction will be applied. The default value is 10 units, but any positive value can be used. However, it would make sense to have this value set to a lower value then the far threshold. If an object is between the far and near threshold, a linear interpolation is used to determine it's reduction value.


Overlap angle

Like the near Cam Distance, this provides the user with a safety zone for rendering. It will prevent an object from being only just outside of view from being reduced at maximal level. Especially usefull for ray trace renderers, when each object generally affects lighting levels. This angle is measured in degrees and the default is 10. The angle affects both sides of the field of fiew of the camera. See the diagram in the report for a simple image displaying the area's of the camera.



Reduction influencing attributes

These attributes affect how the tool actually determines which edge to collapse next. They have been glanced at in the report, chapter 3. For completeness I will give a description here as well.


Redo Mult – After each collapse, all affected edges are updated. It involves recalculating their position and their importance. This multiplier multiplies the final weight after a recalculating operation. Higher values will result in the reduction being more general, where values lower then 1 will focus the reduction in one area. Large reductions with less then 1 “redo Mult” can cause problems for the algorithm though, so please use these values with care. Default value is 1, though general objects like spheres might benefit from a value of about 10, to make reduction more general.


Contour Threshold – Best illustrated by figure 3 in the report, this attribute refers to an angle in degrees. Increasing this angle makes the area of the surface which is part of the contour bigger, allowing special reduction properties to take place there. This could be used to prevent dents appearing in the contour of the surface whilst it is being reduced. The contour importance should be set to a value higher then 1 to view this effect. Valid range is 0 – 45 degrees, with the default being 10.


Contour Importance – Linked to the contour threshold value. Every “edge importance value” that is within the contour threshold area is multiplied by a value which is interpolated from contour importance to 1.


Back facing multiplier – Potentially the most interesting value for users. 1 has no effect, whereas greater values make it more likely for back facing edges to be collapsed. If an edge has been determined to be back facing the following occurs. The number inserted by the user is inverted and consequenly multiplied by the edge's importance, thus producing the final weight. Since high numbers will therefor in affect reduce the importance of a back facing edge, back facing edges are more likely to be collapsed next. The default value is 1 which means back facing edges will not receive special treatment by the algorithm.


Area influence – The last of the attributes which affect reduction. It has not been tested very well, though should work by increasing the importance of edges surrounded by large faces. High values of area influence force the reduction algorithm concentrate on removing small polygons first.





Graph Attributes In View_reduction and out_view Reduction.

These attributes where ment to override the linear interpolation of reduction used when an object is located between the near and far threshold (in view reduction), or inside the near Cam Distance( out view reduction). However, maya's API provides little support for these attributes and as such I have not had time to write the functions to deal with the data provided by these attributes. I have set the MEL script that draws the attribute editor, up to display a linear interpolation. Which is exactly what happens in the algorithm. When a sPolyReduce node is created for the second time in a maya session, these MEL settings appear to be ignored, and as such some error messages will appear when the user opens the attribute editor. These can be ignored though, as they do not affect the working of the algorithm.




Internal Attributes.

The attributes in this closed tab are not designed to change. Provided in this tab are six attributes which are linked to the camear's translate and rotate attributes, as well as two string attributes, showing the object and camera name. Changing these values is not tested as these attributes are there for internal reasons. Hiding these attributes proved troublesome for the automatic updating of my function, so therefor they are still visible to the user,





Extra Attributes

One extra attribute is provided which is called reduction. It only has an affect if the force reduction button is set to on, in the static reduction attributes section. However, changing it's value will always force the tool to update.