This MEL script allows the user to import or export Flair motion control files to and from Maya. The mel script is called “mrmc.mel” and would normally be placed in the default scripts directory. On an Windows system, this might be “My Documents\maya\scripts” which is also where this file: “mel_help.html” should be placed.
If you need to import or export Flair Motion control data, once your have ‘sourced’ the script, you can execute the import only script “mrmcin” or the export only “mrmcout”.
General Data about import and export:
A move is really just a path in space, and the Motion Control space may not be directly related to the Maya space. Getting the move data into or out of Maya is actually the easier part of the process. Making the data line up is more complex, but is conceptually fairly simple. The co-ordinate system and units used are included in the Flair data format and are taken into account. However, you must be working in “Real” units within Maya for the data to work. If you are in centimeters and have built a door 6.8 units high, then it will not match a real door that is 6.8 feet. This is somewhat obvious, but often overlooked. A simple scale of the scene can also lead to confusion since, unless baked out, the animation of the camera is still in its original scale.
In terms of axis orientations, the only thing that is common between the 2 spaces is that Up is vertical. If that is the only stable reference, then the imported move may need to be rotated about the Y axis and translated to make the 2 systems match up. Say, for example, you have filmed a man against green walking through a “doorway” that is marked on the floor of the stage with 2 crosses, and you are supposed to create a CGI doorway for the man to walk through. You either have to create the doorway in Maya at the correct location and at the correct angle in Motion Control space to match the crosses on the floor, or you have to rotate and translate the imported motion control move so that the Maya camera is in the same relative place compared to the virtual doorway as the real camera was to the real doorway. (As a note, Y 0 is not always exactly the floor. Motion control is often put up on cribbing and or blocks to level the track and frequently put on steel deck. If not on steel deck, the the floor and Y 0 are close, but do not assume they are exactly the same.)
One can of course import the move and then translate and rotate the virtual doorway around in space until it matched visually, but this can be very tricky to get exactly right and unless you have perfect visual line up marks, it will seem to work fine for part of the move in one position, and then not for the rest of the move. The recommended way to match moves like this is to use the data source camera (real or virtual) to “survey” at least 2 points on the set that have (or can have) matching components in both the real and virtual worlds. In the above example, the motion control camera would be used to survey the crosses on the floor that represented the actual doorway. A simple move could be plotted that targeted one bottom of the door jamb and moved across to the other. This move could then be exported from the motion control system as 2 points. These points could be plotted in the Maya scene, and the virtual doorway could be moved to match them. In Maya, this is best done with a 2 node camera, as the aim point can be placed exactly on the point you are surveying and this information will come across in Flair as a Focus measurement distance. With a single node camera, you should really triangulate each point or know the distance to the point and convey this information with the export data. Conversely with imported motion control data, you should ensure that the operator has surveyed and accurately measured at least 2 points on the set that can also exist in the virtual world.
If you have built a complex scene, it is often better to adjust the imported data than to move the entire scene around. In this case, the reference points for the doorway would be imported, and then moved around to match the virtual doorway, then these transformations would be applied to the move as a whole. When exporting, you should also include a reference mode as above, but be certain that the camera move and the reference move are in the same coordinate space. (Not parented to differently transformed node).
The single factor that seems to cause the greatest trouble with this sort of data transfer is the “film back”. Understanding and setting the film back correctly either for previs and export or import is a major step towards getting the data and move to match visually. If you are shooting film, and know the format that was shot, you still have to know what was done in telecine or scanning to be able to set this figure correctly. A small zoom in, in telecine will throw this value out, any amount of pan or tilt on the 2D image will equally cause the data not to match properly. With HD there are numerous formats to play with and different generations of cameras sometime have different sizes of chips. (And 2/3” does not mean 2/3” diagonally across a 16:9 chip!) You have to find out as much about this as you can, and shooting a framing leader as well as shooting object a known distance apart from a known distance away can help to calibrate your system.
Zoom Lenses:
A zoom lens can really up the ante on making motion control and cg data match. Whilst theoretically, the lens can easily be modeled in CG, most zoom lenses have aberrations that distort the image. Most will “banana” meaning the centre of the image will shift as the lens zoom, many “pin-cushion” in or out as you zoom. Most zoom lenses also move their nodal point as you zoom, some cheaper lenses have nodal points that move upwards of 2 feet, though the higher end ones seem to be better. This can also throw off the apparent focal length as it is effectively a dolly in or out along the optical axis.
If you are importing a move from motion control, it would be very wise to shoot a pass of the move against a known grid at a known distance. You should also shoot a pass of the move with the zoom locked off at a particular focal length and if time allows a pass with tracking marks or a tracking cube etc.
Rule about visually matching moves:
There is a maxim that has to be followed when transferring data between virtual systems and real systems. That maxim is that you must work from known values and adjust for known and understood offsets between the systems before you start visually tracking. The converse of this is that once you start visually tracking, you have abandoned logically trying to work out the reasons why the move does not match and are stuck with visually tracking the move.
Export
Export is the simpler of the 2 methods, and involves selecting the camera which you wish to export and entering the export file name. The export function supports any of the 3 different Maya cameras (Single Node, Camera with Aim and Camera with Aim and Up). In order for a single node camera to export correctly, it needs to have the same rotation order as a normal film camera. Most film cameras are: Pan, then Tilt, then Roll. This is listed backwards in the rotation order, so a normal film camera has the rotation order z,x,y. You cannot simply change the rotation order of your camera as that will affect the animation, you have to bake out the data to a new camera.
As a note, please try to create a camera that is a realistic size. Most physical cameras are at least 1 foot or 30cm long. If you use a default camera it is usually very small (around 2cm long) and it will not give you a realistic idea of that the real camera needs in terms of clearance.
Export Dialog
Select Camera to Export: This allows you to select any perspective Camera to export.
Export File Name Selection: The name to the file to be created with the export data. Traditionally these are given the .xyz extension.
Create Node Camera (Baking out the data): If the camera you wish to export has the wrong rotation order or its animation is parented on another node, you may need to create a new camera and “bake” your camera's animation onto it to ensure that the data exported is in world space. The default value for this selection is “No”, but you have the option of creating any one of the three camera types (1, 2 or 3 node). Flair is natively a 2 node system, so that would be the recommended format. Single node cameras work well, but occasionally have odd gimbal lock issues or their Euler angles suddenly flip 180 (which can be handled with a Maya Euler filter). A three node camera is useful when you are looking straight down or straight up at any point in the move. It would also be used if you are rotating the world about any axis other than Y since the horizon is changed and this will through the roll out in Flair when you shoot.
If you select “create a new camera” in your scene, one will be created called “MocoBakeCamera”. Any subsequent export actions will delete this camera, so if you wish to save it, you should rename it before exporting again.
Frame Range: When you export the camera, you can define the range of frames over which you want the data exported.
Export Focal Length: You can choose to export the focal length of the lens through to Flair if you are using a zoom lens. The lens would have to have been carefully calibrated for this to work well. If you want to do so, you should select the option “Export Focal Length”. When imported into Flair, the focal length will read into the axis assigned as “Zoom”.
World/Local Coordinates: If your camera is parented to another node, this option will export the world co-ordinates of the camera rather than its own local co-ordinates. This works best with 2 and 3 node camera. It does not work correctly on the rotations for a single node and does not get the roll exactly right on 2 node cameras, so should be used with care. It is a good idea to export the data and then re-import it to a new camera and see if the new camera matches the exported camera. If in doubt create a new camera rather than use the World Coordinates option.
Additional Export: If you have additional data to export to the motion control system (for example a turntable's rotation), you can add up to 6 additional animations onto the file. You must have selected the item you wish to export before you call up the export window. When the window maps, it will list the selected item in the “Additional Export” section of the window as well as listing up to 6 options of the available animatable attributes to export. In order to export an attribute, you must select it in the pulldown menu on the left and also give it a name. The name must be exactly the name that the axis is called in Flair and can contain no whitespace or unusual characters. When this is done, that attribute's animation is exported in whatever native units you are using in Maya and will be added onto the export file as an additional column.
Import
Import allows you to bring Flair camera animation into Maya. The script will read the data header in the Flair Motion Control file and automatically perform the required scaling and axis assignment between the file and Maya. (You must be in Maya Y Up mode which is the default)
The main issue that has to be dealt with on importing data is rotating and translating either the move or the CG world so that they match. Having a reference move or reference positions to import that tell you where something in the real world exists makes the import much more straight forward. There are 2 basic methods of setting up a reference move: 1) Target Survey: Use the real camera to survey real world points that you can easily model in CG 2) Camera Survey: Use the camera to look at point or points in the set where the orientation of the camera is easily matched. (Normally 0 tilt and pan).
Target Survey could be used on the centres of two wheels of a car or perhaps two corners of a table. Camera Survey could be used on a man's eye or a model airplanes's nose. Camera Survey also requires that you make some form or measurement on the distance as well.
Target Survey: If this method is used, then the Motion Control operator will have programmed a move between 2 points that can exist in both worlds. This move should be exported with just the key frames, not a line for every frame. When imported into Maya, the data will come in as a series of locators, for the camera and the target for each key frame, all parented and constrained under a single locator. The parent locator will only rotate about the Y axis. Once this is imported, select the parent locator and move it to put the surveyed points on top of the matching CG points, making sure your camera points wind up on the right side of the surveyed points. If the scale is wrong it will be apparent pretty quickly – the points will not be the same distance apart. Figure out what is wrong and fix it (Do not just adjust the scale until it looks right). When the points are lined up, whatever rotation and translation that had to be applied to the survey points are what needs to be applied to the actual camera move. The other option is to rotate and translate the entire CG Scene to match the imported locators, in which case, that is really all that needs to be done subsequent moves can simply be imported.
Camera Survey: This requires a little more direct contact between the motion control operator and the CG artist. However it is a good method for things that are not as rigidly located or maybe do not have such a clear rotation in space. Typically, the Motion Control operator would use only 1 position, but would line the camera up to be looking horizontal straight at the object to be matched. The distance to the object would also have to be measured and surveyed with the camera or documented. The CG artist would line up his camera in exactly the same way, and then the difference between the different systems cameras' Y rotation and position could be found. The script contains automated features to extract this data.
It is a good idea to shoot a pass of the reference move or to take a reference still of where the camera was to ease the process.
Import Dialog
Select Camera to animate: Allows the user to select any existing camera in the scene to be animated with the import file or to create a new camera. If the data in the file has a different number of nodes to your selected camera, you may have to create a new one. The type of camera created depends on the format of the incoming data. Use “Test File” for more information.
Select File: Opens up a standard file selection box to choose the import file. The text area to the right allows the user to type the file name in if so desired.
Camera Speed?: A radio box that allows you to set the camera speed for the imported move. This data is not intrinsic to the Flair motion control data format. Moves are often shot at different speeds, and it is the transfer/capture speed that is important.
Scale Move: The script will determine the units of the imported file and the currently selected Maya units and do the needed scaling, but this can be useful when matching moves of different scales such as with models etc.
Rotate Move: Rotates the move about the Y (Vertical) axis by the stated number of degrees with anti-clockwise being positive (viewed from above).
Translate X, Y, Z: Translates the imported move by the stated units (Maya Units). If for example, you wanted to lift the move up by 5 units, you would simply type +5.0 in the Translate Y field.
Granularity: The allows you to import every frame as a key frame or to skip keyframing. This helps particularly when you are checking line ups and saving you the time of importing the entire move.
Translate to Selected None/Camera/Target: When you are importing a move to an existing camera, you can translate the imported move to match the selected cameras XYZ position, and if it is a 2 or 3 node camera, you can even translate the move to match the existing Target (if the file is of the correct format).
Rotate to Selected Camera No/Yes: As above, if you are importing to an existing camera, you can also rotate the move so that at the selected frame of the move, the camera will be pointed in the direction it is currently at.
Match Frame of Move: If you are importing a to match the current camera position and/or orientation, you can select the frame of the move which will match. For example, if frame 121 was a good line up frame and you had positioned the virtual camera so that it matches the shot footage perfectly at this frame, then you would enter that frame count into this box, and then the offset to make that frame work for the entire move would be calculated and applied as the move is being imported.
Clear Import Variables: Clears the values in the import translation and Y rotation entry boxes.
Transfer Import Variables: When you have done a “Translate to Selected” or a “Rotate to Selected”, the variables needed to effect the desired transformations are stored in non-editable boxes on the import screen. These values can be copied into the import variables. This would normally be done when you are importing moves after having worked out the required transformations using a line up position.
Upload Selected: This will take the translations and Y Rotation of the currently selected node, and load them into the import transformations.
Reference Point Import
Place Parent Locator at?: The parent locator can be used to move all the Camera and Target locators around until a line up is achieved. This locator can be created at the origin or at the first camera position or the first target position. When it is on the camera or target, it is usually easier to line up - one would simply drag it to the matching point, and then rotate all the locators around it until they matched.
Import Reference Points: This imports the move, but creates a pair of locators for the position of the camera and the position of the target for every frame of imported data. If you use this, it is a good idea to have only key frames in the import file. These locators can be used to determine the correct translations and rotations to be applied to the entire move. Normally, this would be used on the reference move that had been used to line up something in the real footage that matches the virtual world. These locators are all parented to a single locator which can be at the origin, at the first camera position or at the first target position. If this locator is manipulated to line the move locators up with the reference object, then the transformation values of that locator are the correct values to apply to the move to make it line up.
Annotate Reference Points?: Adds a short text reference to aid you in telling the locators apart. The target locators are larger than the camera locators and the first and last will be annotated with “Targ0” and “Targ1” respectively. (Camera locators are called “Cam0” and “Cam1”). The parent locators is also annotated with “Import Parent”.
“Upload Locator Translations + Y Rotation: Takes the rotations and translations from the Parent Locator created when the data was imported and determines what translations and rotation is required to make the move data import correctly.
Import Move: Reads in the move from the file and animates the camera for every line of data.
Test File: This button reports the data found in the file in a concise form to make sure that the file is of the expected format before you import it. It also informs you of the units in the file as well as the axis orientation.
Cancel: When the cancel button is used to close this dialog, the current settings are saved into a small file in the current directory and will be recovered when the dialog is next called up. If you do not wish to save the settings, use the close dialog button on the window frame.
More on Reference Points:
The selection and use of reference points in matching real and virtual images is vital for easy line up. We assume that Up is vertical in both cases, so 2 points which have a reasonable horizontal separation an be used to determine all of the needed transformations (including scaling) to bring the 2 worlds into line. The selection and measurement of these points is important. The points have to be ones that are included in both worlds or can be. In the case of the crosses used above to mark out the doorway; these points do not really exist in the real world, but there is a connection between the 2 worlds that joins the 2 together spatially. In the same fashion, if one were shooting some CG objects on a real table, you could use the 4 corners of the table as reference points, and these could be imported into the CGI world, even though you will not be building a CG table, you could build a reference square to get the lineup correct, and if the square matches the top of the filmed table, then you know the lineup is working. It is also useful to shoot the reference points on film as this will make the process easier as well as verifying that the image has not been moved around in Telecine – if the cross hairs are lined up on the reference pass to know takes, then they should line up in the CGI world as well. (Note: scaling and cropping in Telecine can also cause problems and shooting a framing leader is recommended in all crucial work).
This process also applies to export. Since the problems going from CGI to the real world are basically the same as the other way round, a move should be generated that points the camera directly at specified points in the CGI world that can be used to set up the needed offsets for the move when it is imported into Motion Control. It is also a good idea to line the camera up such that the perspective also helps with the line up. Instead of just aiming the camera up at a corner on a wall, move the camera so that it is looking directly down the wall in one direction, and then the other. This will assist in the line up in the real world. The camera must be in a position it can reach from the track that will be used on the shoot, so try to keep these points as close to the planned move as possible. Consult with the motion control operator for other details.
Additional data may be available at the Camera Control Web Site. Also check the web site for updates on the Mel Script.
Default Settings:
Many of the default settings used on import or export are saved into files called respectively “mrmcin.set” and “mrmcout.set” in the current home directory. These files are read whenever an import or export dialog is called up and so the last used defaults should appear.
Thanks to the many people who have assisted in the writing and testing of this script, particularly: Nic Nicholson, John Schmitt and Oliver Hotz.
Flair Author
(310) 581 8343 Phone
(310) 581 8340 Fax