Digital Geometry Processing

Homework Assignment #1
Due Date 16/11/2019

Introduction
The purpose of this assignment is to help you become familiar with the software framework that we will
be using throughout the course. You will install the necessary software components, learn how to use
them and then you will write a small piece of code that makes a simple use of each of these components.

Please read this entire document thoroughly at least once before you begin to work.

Setup
 You can use the computers in classroom 205 on which Maya, Matlab, and Visual Studio are
already installed. The computers in the classroom are somewhat slow but should still be
useable. If you bump into a technical problem you can contact the IT team or consult with the
course stuff.

 Alternatively, you can install the necessary software on your personal computer.
 Start by installing the Maya 2018 software (free for students). It can be downloaded here:
http://www.autodesk.com/education/free-software/maya. You will need to register at the
Autodesk website in order to obtain a license. It is recommended to download and use the 64bit
version of Maya (and all other software) in order to maintain compatibility with the skeleton
code I will provide you.

 After installation, it is highly recommended to download and install the latest software update
which contains bug fixes and improvements. You can download Maya 2018 update 4 from this
address:
https://dds.autodesk.com/2018/MAYA/532B98D4-EEED-4F6A-A3B8-
67BE57AB7D26/Autodesk_Maya_2018_4_Update_dlm.sfx.exe
 You will also need to have Matlab 64bit and Visual Studio (preferably version 2017) with 64 bit
compiler.

 A free of charge full License for Matlab 2018b for the Engineering faculty students’ will be granted
upon request at this address: http://helpdesk.eng.biu.ac.il/portal.
 Download (from the Moodle website) and extract the provided Visual Studio skeleton code.

 Set the following Windows environment variables according to where the software is installed on
your machine. Here is an example. Adjust it based on your particular configuration:
 MAYA_64_DIR Directory in which Maya binaries are installed. e.g. C:\Program
Files\Autodesk\Maya2018

MATLAB_64_DIR Directory in which Matlab binaries are installed. e.g. C:\Program

Files\MATLAB\R2018b

DGP_CODE_DIR Directory where you extracted the skeleton startup code.

 Locate Maya.env file under My Documents\maya\2018 and add the following lines:

PATH = PATH;%MAYA_64_DIR%\bin;%MATLAB_64_DIR%\bin\win64;
MAYA_SHELF_PATH = %DGP_CODE_DIR%\MEL;
MAYA_SCRIPT_PATH = %DGP_CODE_DIR%\MEL;
XBMLANGPATH = %DGP_CODE_DIR%\MEL;
MAYA_PLUG_IN_PATH = %DGP_CODE_DIR%\plug-ins;

Alternatively, you can copy the Maya.env file from DGP_CODE_DIR dir to My
Documents\maya\2018 dir.

 Make sure you can successfully build the project both in Debug and Release modes. The output
of this project is a single dll file with an .mll extension with a name similar to this:
Debug_x64_DGP.mll or Release_x64_DGP.mll. This file will be located in plug-ins directory under
your code root directory (DGP_CODE_DIR).

 Dynamically load your plugin into Maya by running Maya and then go to the menu Window-
>Setting/Preferences->Plug-in Manager. Locate your mll plugin file in the list and click on the
checkbox next to “Loaded”. If the check mark is set it means that your plugin was successfully
loaded, otherwise open the script editor to see if the load failed. This can be done by using Maya’s
menu Window->General Editors->Script Editor. You can also check “Auto load” in the Plug-in
Manager which will ensure that your plugin is automatically loaded whenever Maya is. However,
note that you must unload the plugin whenever you want to rebuild it in VS (Visual Studio).

Programming
Implement a Maya command named “colorMeshVerticesCmd” by deriving from the class MPxCommand.
An example for a different MPxCommand command (look for “TriangulatePolygonCmd”) is already given
to you as part of the startup code. Make sure you register/unregister your new command when your
plugin is loaded/unloaded (see the file pluginMain.cpp). You can also use the following Maya
documentation in order to learn more about Maya commands:

http://help.autodesk.com/view/MAYAUL/2018/ENU/?guid=__files_Command_plugins_MPxCommand_
htm
The command should get as a parameter a triangle mesh. It is advised to verify (in your code) that the
mesh contains only triangles before proceeding to avoid any processing errors. If for some reason, the
input is not a triangle mesh, issue an error to the Maya user.

Your command should create two empty color sets. The first should be named: “Valence” and the second:
“Curvature”. Once the color sets are created, they should be filled with appropriate colors. If color sets
with such names already exist, their content should be eliminated.

For the valence, use the following color coding:

Valence Red Green Blue

≥9 255 0 0
8 0 0 255
7 255 255 128
6 0 255 0
5 255 0 255
4 0 255 255
≤3 128 0 255

For Gaussian curvature, use the provided “Matlab Jet Color Map”. See the mapColor helper function in
Utilities.h (provided code) which converts a scalar value such as Gaussian curvature into R,G,B triplets.
Your new colorMeshVerticesCmd command should accept two optional flags: “-min” and “-max”. If these
flags are provided, they should be used to adjust the dynamic range of the color (see parameters for the
provided mapColor function). Otherwise, the minimum and maximum of the Gaussian curvature of the
mesh vertices should be computed automatically. Your command should also issue a call to
MGlobal::displayInfo in order to display to Maya’s script editor the min and max values.

The discrete Gaussian curvature of a triangle mesh is defined to be the deficit angle at a specified vertex.
For a non-boundary vertex, the Gaussian curvature is given by the formula: 𝜅 = 2𝜋 − ∑𝑛𝑖=1 𝛼𝑖 where n is
the number of neighboring triangles and 𝛼𝑖 are the angles of the adjacent triangles. Note that for a flat
surface such as a plane, the Gaussian curvature is zero (this fact can be used to debug your code!). For a
curved surface, the Gaussian curvature can be either positive or negative. For a boundary vertex, the
formula is slightly different and is given by: 𝜅 = 𝜋 − ∑𝑛𝑖=1 𝛼𝑖 .

Hint: In order to perform the curvature computation, it is usually easier to iterate over triangles/faces
rather than iterating over vertices.

Your next task is to implement the command “inverseMatrixCmd”. This command accepts a 3x3 matrix
represented as a list of 9 consecutive numbers in row major format (first row followed by second row
followed by third row) and returns its inverse matrix (if it exists). In order to compute the inverse you
should use the Matlab-Maya interface code (provided). First, create a matrix in C++ by using the GMM++
library which is also provided as part of the code. Use the GMMDenseColMatrix type defined in
GMM_Macros.h. GMM is a simple to use C++ template dense/sparse matrix library. We will use GMM as
data structures (containers) to hold matrix variables but will not be using it to perform sophisticated
matrix operations (such as inverting a matrix). All matrix operations will be done in Matlab. Your job is to
use the Matlab-Maya interface code in order to transfer the GMM 3x3 matrix to Matlab (see
MatlabGMMDataExchange.h in the code). Then invoke a Matlab script that will invert the matrix. Invoking
a script (or a function) can be done by using 'EvalToCout' function or one of the other alternatives in the
file MatlabInterface.h.
For example, the following C++ line:

MatlabInterface::GetEngine().EvalToCout("My_Matrix = [1 2 3; 4 5 6]");

will create and initialize a 2x3 matrix in Matlab with name My_Matrix.
Please save any new Matlab script you create under DGP_CODE_DIR\Matlab folder.
You should add this folder to Matlab’s path. See this:
https://www.mathworks.com/help/matlab/ref/pathtool.html

Finally, transfer the result back to Maya and print the inverse matrix to the standard output console (in
order to print a matrix to the standard output of Maya, you can simply use a statement like this: cout <<
gmmMatrix; ).
The full GMM documentation is available here: http://getfem.org/gmm/index.html

Here is an example of interaction between Maya’s code and Matlab’s:

MatlabInterface::GetEngine().EvalToCout("My_Matrix = [1 2 3; 4 5 6]");
GMMDenseColMatrix M(2, 4);
M(0, 0) = 8.0;
M(1, 2) = -4.0;
int result = MatlabGMMDataExchange::SetEngineDenseMatrix("M", M);

GMMDenseColMatrix My_Matrix;
result = MatlabGMMDataExchange::GetEngineDenseMatrix("My_Matrix", My_Matrix);
cout << "printing the GMM Matrix: " << My_Matrix << endl;

Here are few tips regarding the implementation:

Tip 1: When you are using Maya’s iterators such as MItMeshVertex, it is important not to change the mesh
object (say by calling createColorSetWithName) while using the iterator as it might invalidate the iterator.

Tip 2: It will probably be easier to use MFnMesh::setVertexColors rather than MFnMesh::assignColors.

Tip 3: Use the plural version of setVertexColors/assignColors rather than setting the colors one by one.
Your code will run much faster.

Tip 4: call MFnMesh::setDisplayColors(true) after you assign the right colors to your mesh in order for
Maya to display the colors in the UI.
Testing Your Plugin
Debugging of Maya C++ plugins is easy. In order to do that you will have to go to the project setting dialog
box. Under “Debugging”, make sure you set “Attach” to yes. Also set “Command” to point to Maya.exe
application. e.g. C:\Program Files\Autodesk\Maya2018\bin\maya.exe. It is best to run the Maya
application from outside the VS environment. This way it will keep running even if you stop the debugger
(unless you crash the application with your own code). This will allow you to quickly edit your code and
rebuild your plugin while avoiding restarting Maya.

You can create simple mesh objects from within Maya in order to test your plugin. For example, go to the
menu “Create->Polygon Primitives->Sphere” to create a polygonal sphere. It is recommended that you
convert the polygon mesh into a triangle mesh by using the following Maya menu command: “Mesh-
>Triangulate”. Note: Maya has several alternative menus but only one is active at a time. Make sure that
the “polygon” menu is the active one if you want to invoke the above mentioned commands.

Alternatively, you can load into Maya a scene with objects taken from external sources. Beside the native
support for its own .ma/.mb scene files, Maya supports import and export of many other file formats such
as obj/vrml etc. Also, the package: “3D Models.zip” which can be found on the course website contains
several nice models you can use in order to test your code.

Getting Started with Maya

If you want to get a better feel for what Maya has to offer to the end user (not the programmer), or if you
would like to be able to operate Maya more smoothly, consider going over the following resource:

http://help.autodesk.com/view/MAYAUL/2018/ENU/

As a programmer who uses Maya as a software framework to develop custom plugins, you should get
familiar with the following API guide:

http://help.autodesk.com/view/MAYAUL/2018/ENU/?guid=__files_Maya_API_introduction_htm

Maya is huge software with a lot of possibilities for further extensions. Maya offers three types of API:

1) C++ API
2) MEL Scripting API
3) Python Scripting API

The C++ API is a powerful tool for creating efficient software that is seamlessly integrated with Maya.
Maya provides a set of C++ classes that allows the programmer to interact with internal Maya’s objects.

The full list of classes is available here:

http://help.autodesk.com/view/MAYAUL/2018/ENU/?guid=__cpp_ref_annotated_html
Some particular classes which are relevant to us are: MFnMesh, MPxCommand, MItMeshVertex,
MItMeshPolygon, MItMeshFaceVertex, MItMeshEdge.

MEL is a propriety scripting language used in Maya. It is very similar to C. The advantage of using a scripting
language is in its simplicity and fast development (just like Matlab). It is especially convenient to use MEL,
however, the C++ API covers almost everything that is covered by MEL so it is not mandatory.

The entire built-in MEL commands set is listed here:

http://help.autodesk.com/cloudhelp/2018/ENU/Maya-Tech-Docs/Commands/index.html

The Python API is similar in concept to MEL. It provides the same functionality of MEL, only via a slightly
different scripting language. In addition, it has the ability to invoke the C++ API.

MEL and Python are executed from the “script editor”. Once you will implement your C++ MPXCommand,
you will need to execute your MEL/Python command by using the script editor. Alternatively, you can
create a custom shelf button that executes your command every time it is being pressed.

Submission
Please submit a single zip/rar file to the Moodle website before the submission deadline. The file should
include all the code of your project including the code that we provided as well as the code you
created/modified in such a way that we will be able to open the Visual Studio solution and build it directly
without any trouble such as missing files or ther compilation errors. Points will be reduced for submissions
that do not satisfy these rules. In order to make the package file you submit smaller in size, please remove
any unnecessary files from your submission. Visual Studio generates a lot of temporary files that are not
needed such as temporary build files etc. In particular Visual Studio 2017 creates a hidden folder named
.vs which can be removed. If you don’t see it make sure your Windows settings allows you to see hidden
files.

Make sure you also include a compiled plugin mll file in Release mode (64 bit) as opposed to the default
debug mode. Release mode compilation optimizes your code such that it can run much faster. Debug
mode is slow and you should use it for code development but the final software should always be built in
Release mode. After you build the Release mode plugin, make sure it also runs correctly. Some errors only
occur in Release mode while others only occur in Debug mode.

Please provide a short readme.txt file which explains how to use your plugin, including any input
parameters that are being used such as usage of command flags and parameters etc.

Do not email your zip file to me!

Grading
Closer to the deadline, I will create ~15 minute time slots in which you will be able to demonstrate your
program to me. During presentation, we will download the code that you uploaded to the Moodle, build
it and test it together.

The Forum
You will find a questions and answers forum on the course website. You should use this forum to ask
questions about the homework assignments or any other subject that is relevant to other students.
Please email me only if you have a personal matter you would like to discuss. For general course related
questions, use the forum. This way, other students will be able to read the answers and will learn from it
as well. Moreover, feel free to help your friends and answer other students’ technical questions. Make
sure you are subscribed to read email alerts for new posts on the course forums.

Enjoy your work!

The course staff