Home
Welcome to XROMM Blender Tools.
This wiki will provide an overview of the tools available, and how to use them. XROMM Blender tools were written by Peter Falkingham, and aim to replicate (a subset of the) functionality of XROMM Maya Tools by Dave Baier.
- Installation
- Importing cameras and image planes
- Importing objects
- Applying rigid body transformations
- Importing XYZ translations and rotations
- Creating Axes
- Calculating relative motion
- Visualizing motion data
- Exporting Data
- Creating CT markers (vAVG)
- Exporting CT markers
- Interoperability of scenes between Blender and Maya
Download the latest zip file from the releases page. In Blender, go to Edit -> preferences -> add-ons and then install from zip. It should appear in the add-ons list, and be ticked:
If installed correctly, an XROMM tab while appear on the right of the viewport:
XROMM Blender tools currently only works on the MayaCamv2 exported from XMALab. v1 support is unlikely to be implemented, having been superseded by v2.
Having exported maya cam files from XMALab, select the file in the XCam tab. If you exported undistorted images from XMALab, you can select the first of these, and tick 'image sequence?'. You can also load a single image (e.g. of the calibration cube), or a movie file (AVI, MP4, etc).
You should also name your camera. Note that if the name already exists, blender will append .001 (then .002, .003, etc).
You'll need to turn on viewport shading to see the textured image plane.
Note that a relationship line appears between the camera and image plane (this can be turned off in overlay options).
The image plane can be moved only parallel to the camera, and should scale such that it covers a constant field of view:
To view through an xcam, open the sidebar, go to the 'view' tab, and set the active camera to the camera of your choice. You'll then view through active camera to use that camera as is. To replicate the PSTR tool from XROMM Maya Tools, just untick 'lock camera to 3D view', and you can then pan and dolly without affecting the camera/image plane alignment:
XROMM Maya tools included an option for importing objs via the imp tool. In XROMM Blender tools we rely on the native obj import to bring meshes in. File -> Import, select file type, then select file.
Select the object you want to apply rigid body transformations to, in the image below that's the cranium, then in the XROMM sidebar, expand the 'Import XYZ or motion Data' tab and select the rigid body transformation file exported from XMALab, and click 'Import Data to Selected Object':
Note that unlike XROMM Maya Tools, this is almost instant, and does not play through the timeline, nor does it set the timeline to the number of animation frames.
If you want to set transparancy whilst using Viewport shading or EEVEE renderer, you need to set the Alpha of the material, but also enable backface Culling and set Blend Mode to 'Alpha Blend' for that material:
You can also use the import panel to bring in XYZ translations or rotations, which may be a single frame or animated. These translations/rotations can be applied to existing, selected objects, or to new spheres. This is useful if, for instance, you want to bring in the XYZ locations of the calibration cube for checking data, or if you have individual markers not attached to bones (e.g. muscle markers).
Select the csv file as for rigid body transformations, then select either translations or rotations in the checkboxes (Translation is selected by default, Rotation is not). Then select if you want these data to be applied to new spheres (which will take the name from the header), or to selected objects. You need to select objects in the order that you want the data applied to them.
The CSV should take the format:
object1_x, object1_y, object1_z, object1_rx, object1_ry, object1_rz, object2_x ...etc
followed by numerical data.
Translations and Rotations are optional, so if you had a file with just translations, _rx, _ry, _rz would not be present, etc (you can technically untick both Translation and Rotation, but then nothing will be imported).
New spheres are hardcoded to be 1cm in diameter, but can be scaled manually later.
If data occurs on multiple lines, each line will be taken as a new frame. NaN can be used to pad frames in the file (e.g. if data start at frame 100, you'd need 99 lines of NaN, NaN, NaN, etc.
If you import multiple objects and want to scale them all without changing their position, select all the objects then set transform pivot point to 'individual origins':
You can then adjust scale without them moving towards/away from each other.
Under the 'Axes and Rel Motion' panel, there are two options for creating axes, with or without locators. This follows the same workflow as XROMM Maya Tools. I have not implemented hemi-axes, only full, and the size is currently hardcoded at 5 cm.
Start by setting the timeline to a position where your bones are in 'neutral' or 'zero' position. This may be CT space, key-framed at frame 0, or it may be a part of the animation where the bones are in a certain position (e.g. for the pig dataset, where the mouth is fully closed).
Creating axes **without **locators, will generate a new axis object with the name specified. This will be a single object, with red, green and blue axes representing X, Y, and Z. Move the axis object by hand to where you want it in accordance with your joint coordinate system.
Creating **with **locators will generate an axis object as above, but with two locators (empty arrows) that determine the orientation of the Z axis. Move each locator to a side of the joint (I recommend enabling vertex snapping to snap them to the mesh). The axis object will align with them. You can then use the rotate tool to orient the X and Y axes of the object in accordance with your joint coordinate system (Z should be in the line of most rotation, then Y, then finally X, as for the Maya workflow).
Ensure that your timeline is in a place where you would consider the motion to be zero, and that your axis object is correctly oriented. Then select the axis object, proximal object, and distal object (these terms are slightly confusing for e.g. skulls, but you will have your own convention for this).
You can select the objects by using the eyedropper tool, clicking in the box and selecting from a list, clicking in the box and typing its name, or dragging the object from the outliner to the box.
Click 'Calculate relative motion', and the relative motion between the two objects (proximal and distal) will be calculated. The specified axis object will be parented to the distal object, and a duplicate (Prox) will be parented to the proximal object. An empty with the same name as the original axis but the suffix '_Data' (i.e. _Data) will be created in the scene, and its translations and rotations will be the relative motion between the proximal and distal objects.
To visualize the data on the axis_Data object, change the view (or open a new window) to the graph editor, using the editor type button in the top left:
You can then view XYZ translations and rotations representing the relative motions between your proximal and distal objects. Here is the Pig Feeding data:
Z Euler rotation here shows the mouth opening and closing. You can play with line thickness and colours, and turn off view handles, to get better visualization of the curves. Best settings will depend on your personal Blender theme.
Having calculated relative motion between two objects, you may now want to export this motion data to csv for further analysis, or visualization. To do so, select all _Data objects you wish to export data for. There are three check boxes in the menu:
Animation, if checked, will write out data for the full timeline. If unchecked, only data for the current frame will be exported. Each frame will be a new line in the output file.
Translation and Rotation determine if translation and/or rotation are exported. You can export both, or one (you can technically export neither and have a blank file.
The output file will contain a header row describing each column, e.g.:
joint2_Data_x, joint2_Data_y, joint2_Data_z, joint2_Data_rx, joint2_Data_ry, joint2_Data_rz
-0.026590585708618164, 0.1744213104248047, 0.04173421859741211, -0.48922414541150505, 0.0312792681857366, 3.844748915406497
-0.04173469543457031, 0.18427515029907227, 0.021346330642700195, -0.44945451519545954, 0.000996353324073531, 4.1064540167578825
-0.04167032241821289, 0.184326171875, 0.02142167091369629, -0.4499066950628555, 0.00037480644831872203, 4.106950059246355
-0.057942867279052734, 0.19927775859832764, 0.01659560203552246, -0.5355960072340141, 0.29396397807964986, 4.472716080810646
-0.04289078712463379, 0.22357845306396484, 0.02605128288269043, -0.6155278434608221, 0.03133177860003438, 5.1121784545879265
-0.04523301124572754, 0.24915802478790283, 0.04247784614562988, -0.7733601749665941, 0.055697181128318965, 5.775160157885323
-0.06379508972167969, 0.26399707794189453, 0.027663707733154297, -0.7889581392359347, 0.15192464476053408, 6.420556685390876
This appears in XROMM Tools for Maya as 'vAVG' and averages vertices to locate a geometric centre. This is used for selecting a segmented CT marker and finding its position.
There is a checkbox separate objects, which if selected, will break the mesh into constituent parts (using mesh->separate by loose), and then find the centre of each part. This is useful if, for instance, you segmented all your markers via thresholding, and exported a single obj or stl file. If the box is unchecked, the centre will be found of all verticies in the selected mesh. Note that the splitting of the mesh is not undoable. If you wish to recombine the separated mesh parts later, use object->join
There are two options: accurate and fast, determined with a toggle button.
Accurate is mathematically identical to the original Maya scripts, in that it will calculate the position based on the average location of each vertex in the model. However, this can be susceptible to cases where a given marker might have many more vertices at one end, resulting in an average position that is not in the centre of the object.
Fast, conversely, uses the object's bounding box to find the centre. This will be more accurate for rounder, more uniform marker meshes, and significantly faster where there are many vertices. However, this method will be slightly incorrect if the markers have concave areas or are oddly shaped.
In my testing, there's almost no difference in location between the methods, and any variation will probably be less than the errors in tracking and segmenting. However, users are advised to run their own checks first. Use Accurate if you want to stick to the original maths of the maya scripts.
Select all markers you wish to export positions for. If you've created them with the above method, they should have a prefix of 'm_' meaning they can easily by filtered and selected in the outliner:
If you click the 'Export marker positions' with the relevant markers selected, you will be given a file picker to choose where to save the file. The file will follow the format outlined above for exporting motion data, but will contain only translation data:
m_Cranium_x, m_Cranium_y, m_Cranium_z, m_Cranium.001_x, m_Cranium.001_y, m_Cranium.001_z, m_Cranium.002_x, m_Cranium.002_y, m_Cranium.002_z
12.69406509399414, 8.168843269348145, 14.495115280151367, 14.354568481445312, 4.850256443023682, 22.676450729370117, 14.43957805633545, 4.888597011566162, 22.613536834716797
Finally, I want to discuss interoperability between Blender and Maya. I am very wary of splitting the XROMM community between Maya and Blender. As a reminder, most of the expertise in XROMM is currently firmly embedded in using Maya. However, recent advances in the 3D industry have seen improvements in the USD format. In my testing, if you save to USD , the file can be opened in either software, retaining *all data except the image sequences for the image planes (which are already a pain to transfer between two people using the same software). The following settings when saving as USD have been successful in my testing so far:
The scene exported directly from blender to USDc, and opened in maya, retains all animations, materials, and data (except image plane sequences):
