The functions in this collection can be used to add FV mesh structs, 3D scatterplots and 2D xy plot data to a a cell array called xFigureObject. xFigureObject can then be viewd in an external interactive 3D viewer app (creatively called "MatlabViewer"), which is released with this collection.
The goal of this app + functions is to make it easier/faster to explore 3D meshes. The app, which was built using the game design platform Unity3D, allows the user to navigate around the exported meshes faster and with higher quality surface rendering than is generally possible using matlab figures (especially for larger meshes), using the Unity Game engine. Meshes can be rendered with a single, solid colour or using values of a surface function (+colormap) to define vertex colors (similar to 'facevertexcdata'). A set of multiple surface functions/vertex colors can be defined for a mesh. A slider in the app can be used to rapidly switch between veertexcolor datasets to explore different surface data on the same mesh in 3D.
In addition to meshes the app can display 3D scatter-plots (as spheres of user defined size and color). 2D xy plots can be displayed in an inset window
At the moment the Unity built Matlabviewer and the export functions are still somewhat experimental and under development. I bulilt them for specific use cases in an ongoing project and even though I tried to generalize them where I could, they may therefore not be well suited for some other tasks. Since this is still very much a work in progress I woud appreciate any feedback you might have (by email or as comments). If this viewer proves useful to other users I would be happy to keep improving and extending it to include other needed capabilities.
I tested the current version on MacOS 10.14 with Matlab 2019b and it runs smoothly. I tried to build it so it should also run on Linux and Windows, but have not been able to test it yet. Feedback on OS related issues/bugs would be appreciated.
The display of mesh faces is dependent on the orientation of the face normal. Since matlab follows the right-hand rule, but unity uses left handed coordinates this can cause issues (there is a step in the export function that switches the handedness, but if the face ordering is not as expected issues might still arise. In an earlier version XfigurePatch.m did not have this so it would need to be fixed manually). If the face normal is inverted (i.e. a normal vector following the left hand rule does not point "outwards") the mesh can display "inside out" (only the inside face of the mesh will be visible). If this occurs it can be fixed by simply switching 2 columns in fv.faces. Meshes that have a mixed orientation of face normals will not display correctly.
temp = fv.faces;
fv.faces(:, 1) = temp(:, 2);
fv.faces(:, 2) = temp(:, 1);
The source files for the MatlabViewer Unity Project are located in a seperate git repository: https://github.com/JBKacerovsky/MatlabViewerUnityProject
also see demo_Xfigure.m
start by calling
Xfigure;
this creates a new empty cell array in the current workspace called xFigureObject (or clears existing cell arrays of that name). All further data will be added to this cell array:
once the figure is defined export it and launch the app by calling
XfigureExport("name", 1); (0 if you don't want to launch thee app yet)
this will save xFigureeObject to a folder called "streamingAssets" in the app datastructure
XfigurePatch - adds FV mesh with vertex colors. If the vertexcolor array has >1 column it will be added as a variable vertexcolor mesh. In the current version only one variable vertexcolor mesh should be defined per scence/xFigureObjectXfigurePatchSingleColor - adds FV mesh with a single color
XfigureScatter3 - adds 3D scatter plot from array of point locations (xyz coordinates)
XfigureGraph - adds 2d xy plot from y data array. if the ydata array has >1 column it will be created as a variable data 2D plot. In the current version the y-data for variable data plots should have the same number of columns as vertexcolor columns of a variable XfigurePatch
XfigureSetCameraDistance - allows the user to define the starting7default location of the camera (default if not defined = 3000). the camera will alwas be located at x=0 and y=0 at the start and point at 0,0,0. Using this function the user can define the z location of the camera (i.e. distance from the center of the scene)
XfigureClear will delete all previously exported xFigure files from the StreamingAssets folder, exceptions can be defined manually
XfigureLs will display the names of all currently saved xFigure files in the StreamingAssets folder
xfigureDisplay launches the app
the app always launches empty. you can launch the app directly as a program or from Matlab (depending on security setting you might have to give permission) by calling XfigureDisplay or when calling XfigureExport by setting the DisplayFigure value to one
to display an exported scene, select the figure by name from the dropdown menu and click "UpdateFigure" (this can also be used to update the figure if the data has been changed)
to unlock navigation (rotation and zoom) click the button "Camera Orbit" or click the "C" key. Once unlocked the view can be rotated (around the center) by using mouse click+drag. To zoom use mouse scroll. By clicking "Camera Orbit" or the "C" key again the view can be locked.
to unlock panning click the button "Camera Pan" or click the "P" key. Once unlocked the view can be panned (also changing the center of rotation) by using mouse click+drag. By clicking "Camera Pan" or the "P" key again the view can be locked.
to unlock rotation of the light sources click the button "Light Orbit" or click the "l" key. Once unlocked the lightsourcees can be rotated around the centre of view by using mouse click+drag to change the angle of illumination . By clicking "Light Orbit" or the "L" key the position of the light sources can be locked.
to show/hide the graph inset click the button. the size of the inset window can be changed using the buttons in the lower left corner of the inset.
if a mesh is defined as a variable data mesh (i.e. >1 column for vertexcolors) a slider will appear at the bottom of the Viewer. This slider can be used to select which dataset/column should be displayed and to navigate between them. If a variable data plot is defined the slider will also set wich dataset should be displayed. (note that in the current version the slider appearance is set ONLY by the mesh object. therefore a variable data plot can only be displayed properly if there is also a variable data mesh with the same number of data columns)