CLOUD DIGITISER 2014 Interactive measurements of point cloud sequences July 2014 Cloud Digitiser Manual 1
CLOUD DIGITISER Interactive measurement of point clouds Bill Sellers July 2014 Introduction Photogrammetric reconstruction of video clips produces a folder with sequentially numbered.ply files containing the reconstructed point clouds. However these are uncalibrated both in terms of orientation and also scale. Typically these clouds will need to be oriented and scaled to match some desired coordinate system. Once this has been completed, it is generally useful to be able to measure features visible in the point clouds and to produce series of position data as objects move. Cloud Digitiser is a program written to assist these activities. Installation The installation method depends on the platform. On a Mac, you simply double click the supplied.dmg file and drag the application icon into the Applications folder (or elsewhere if preferred) on your hard disk. On Windows, you need to uncompress the.zip file into a folder and drag this folder to a convenient location on your hard drive. All the files within the folder must be present for the application to work. On Linux you will need to compile the application from source using the Qt system. Once installed, you can run the application by double-clicking its icon. Basic Operation The program allows you to select a ply file and will display it on a set of 4 panes representing views from the X, Y and Z directions. The 4th view is a user specified orientation. The program provides a series of tools that let you re-orient and scale the 3D file and once you are happy with this, it allows you to write out the 4x4 homogenous matrix that represents the final transformation that you have performed. Once this matrix is stored in a file, you can use the batch mode to apply this transformation to all the ply files in a folder. You can also generate the matrix externally if the tools available are not suitable. The program also allows you to take measurements on point cloud data and will automatically save all measurements made since it was started. These can be saved as a text file for use elsewhere. Cloud Digitiser Manual 2
Main Window Figure 1. Main Window showing the controls and menus available. Interaction with the window contents is primarily by a series of buttons at the top of the window. Their functions are as follows: Select Point tool. Selects points within a user specified radius of the location clicked in any pane. Select Line tool. Selects points within a user specified radius of the line drawn in any pane. A click with no drag deselects all points. Select Rectangle tool. Selects points within a rectangle drawn in any pane. A click with no drag deselects all points. Drag tool. When selected, it allows the contents of the window panes to be dragged and rotated. This affects the view not the model. Nudge tool. When selected the x, y and z keys cause a small rotation about the X, Y and Z axes. If the shift key is pressed then the direction of rotation is reversed. The model is affected. Cloud Digitiser Manual 3
Fit Point tool. Fits a point to the selected points in the views. Generates a point. Fit Line tool. Fits a line to the selected points in the views. Generates a point and a direction vector. Fit Plane tool. Fits a plane to the selected points in the views. Generates a point and a normal vector. Left Arrow tool. Opens the ply file alphabetically previous to the current one in the same folder. Right Arrow tool. Opens the ply file alphabetically subsequent to the current one in the same folder Best Fit tool. Moves the view point so that the whole model is visible in all the window pains. Cloud Digitiser Manual 4
There are also a series of menus that allow other functions. Preferences Activates the preferences dialog box. Quit CloudDigitiser Quits the program. Cloud Digitiser Manual 5
Open PLY File Allows the user to choose the ply file to open. Apply Transformation Matrix Allows the user to apply a transformation matrix that has previously been stored in a file on disk. The format is simply 16 floating point numbers separated by whitespace representing the homogeneous transformation array. Save As New PLY File Save the currently open ply file as a new file including any transformations that have been applied. Save Transformation Matrix Save the current transformation matrix Save Measurements Save the text file containing all the measurements since the program was started. Cloud Digitiser Manual 6
Rotate to X Rotate the model so that the currently fitted vector is oriented along the X axis. A line or plane must have been fitted to provide the vector. Rotate to Y Rotate the model so that the currently fitted vector is oriented along the Y axis. A line or plane must have been fitted to provide the vector. Rotate to Z Rotate the model so that the currently fitted vector is oriented along the Z axis. A line or plane must have been fitted to provide the vector. Rotate to X about Z Rotate the model around the Z axis so that the currently fitted vector is oriented as closely to the X axis as possible. A line or plane must have been fitted to provide the vector. Rotate to Y about Z Rotate the model around the Z axis so that the currently fitted vector is oriented as closely to the Y axis as possible. A line or plane must have been fitted to provide the vector. Cloud Digitiser Manual 7
Rotate to Z about X Rotate the model around the X axis so that the currently fitted vector is oriented as closely to the Z axis as possible. A line or plane must have been fitted to provide the vector. Rotate 180 about X Rotate the model 180 around the X axis. Rotate 180 about Y Rotate the model 180 around the Y axis. Rotate 180 about Z Rotate the model 180 around the Z axis. Set Origin Sets the model's origin to be the currently fitted point. A point, line or plane must have been previously fitted. Calibrate Point Activate the calibration dialog box. Cloud Digitiser Manual 8
Batch Transform Activate the batch transform dialog box. Measurements At (almost) any point when there is a model loaded and none of the dialog boxes are visible, the keyboard can be used to make measurements. This is done by positioning the mouse over the point desired and pressing any letter or digit key. When the key is pressed a point is calculated from the mean of the points within a user specified radius of the clicked point. This point is labelled on the model using the letter of number, and stored in the measurements file associated with the filename of the current ply file. Thus a maximum of 36 measurements can be taken from each ply file. The ply file itself is not altered. If you want to delete a particular measurement then shift-click the letter. The measurements file starts with a number that specifies the number of ply files measured. Then each ply file starts with the pathname on a separate line, followed by the number of measurements taken on that ply file. Each measurement starts with the single character for that measurement followed by the x, y and z coordinates. This should be fairly straightforward to parse in Matlab, R or whatever analysis package you use. Cloud Digitiser Manual 9
You can rapidly step through a series of ply files in a folder using the left and right cursor keys or the left and right tool buttons. If you take no measurements on a file, then it will still create a section but it will contain no measurements. Preferences Dialog This dialog allows the basic options to be set. Use pixels for selection sphere If checked, the selection sphere radius is in screen pixels. If unchecked the selection sphere radius is in the current model coordinates (which may be uncalibrated). Cloud Digitiser Manual 10
Load previous file at startup If desired the program can automatically load the last file that was opened in the previous session. Selection sphere radius Point and line selections select all points within a certain radius of the screen selected region. It is specified her and the units depends on the selection sphere units chosen above. Camera distance CloudDigitiser uses a parallel projection so camera distance does not affect the shape of the image. However this distance is used for clipping and for Z-buffering so it should be big enough but not to big. 10 time the likely model size if often a good number. Maximum display points Cloud digitiser will load all the points in the ply file into memory. However it will only display a uniform subsample. If performance appears slow then it may be useful to reduce this. Nudge angle (degrees) The angles the nudge buttons move the model by for each key press. Colours Sets the colours of the user interface elements. Cloud Digitiser Manual 11
World Calibration Dialog This dialog allows the scale of the model to be changed. The values in Model are the X, Y, Z coordinates of the last fitted point. When OK is clicked, the program will calculate the scale factor(s) necessary to scale from this X, Y, Z position to the world X, Y, Z position that should be specified by the user. If Uniform Scale is selected then only a single scale factor is applied uniformly to all 3 axes. It is calculated using the largest World/Model scale factor so in this case it would be 1/2.3858471. The sign of the scale factor is ignored. If a scale factor has been calcuated externally - perhaps from the separation of the cameras - then this value can be put in the Fixed Scale box and the Fixed Scale checkbox selected. In this case, all other settings are ignored. Cloud Digitiser Manual 12
Batch Process Dialog This is the front end for applying a transformation matrix to all the ply files in a folder. You specify the Source Folder that contains the untransformed ply files; the Destination Folder that probably should be empty because any name clashes will lead to files being overwritten; and the Transformation File which is a text file containing the homogeneous transformation matrix as a series of 16 floating point numbers. WARNING: this procedure can take an appreciable amount of time and the program currently does not allow any interaction one it has been started. Also this program will overwrite files in the Destination Folder if their names match. Suggested Workflow Here is the suggested workflow to take measurements from a series of ply files stored in a folder. 1. Open one of the original ply files. It will display in an arbitrary orientation and origin. 2. Select something to represent the up direction. This can be a vertical line, a set of points arranged vertically, or a horizontal plane (because the normal will be vertical). 3. Fit a line or a plane to the points as required to generate a suitable vertical vector. 4. Use the Rotate to Z menu option to rotate the model so that the fitted line is vertical. 5. If it makes sense you can now define one of the other directions by selecting points, a line or a plane. Use the Rotate to X about Z or Rotate to Y about Z menu options to orient this additional direction. Generally speaking you should only specify one additional direction since this will automatically define the missing axis. Cloud Digitiser Manual 13
6. You model may now be upside down. Use Rotate 180 about X or Rotate 180 about Y to fix this. 7. Select a point to define the origin of the model. 8. Fit a point to the selected point. 9. Use the Set Origin menu to define the origin. 10. Select a point of known world coordinates on the model. 11. Fit a point to the selected point. 12. Use the Calibrate Point menu option to pop up the World Calibration Dialog. Type the coordinates of the know point into the World section and make sure that Uniform Scale is checked and that Fixed Scale is not checked.if the scale factor is known externally - perhaps from the camera positions extracted from the bundle file - then instead of 10 and 11, just check the Fixed Scale box and type in the known scale factor. Click OK. 13. You can now save the transformation matrix using the Save Transformation Matrix menu option. 14. Create an empty folder to store all the new ply files you are going to create. 15. Use the Batch Transform menu option to pop up the Batch Process Dialog. Set the Source Folder to the folder containing all the raw ply files, set the Destination Folder to the newly created empty folder, set the Click OK. to the newly created transformation file. 16. Click OK and go and make a cup of tea. It will take several minutes to process all those ply files. Potentially several hours if you have a lot of them or they are very large. 17. Select the New Measurements menu item. This is because the measurements file contains every file you have opened since you started the program and this will include the raw ply file that you probably do not want to include in the measurements file. 18. Open the first transformed ply file in the new folder. 19. Move the mouse over the positions you want to measure. Click a letter or number key for each point you want to measure. You need to decide in advance how the characters will code for the measurements that you want and you need to be consistent. If you press a character more than once, then the last position is the one saved. You can also shift-click to delete measurement points. This makes correcting mistakes easy. Measurements are also automatically copied into the clipboard for easy pasting into other programs: handy if you only want a few measurements. Cloud Digitiser Manual 14
20. Once you have all the measurements you want for a ply file, open the next one using either the Open PLY File menu option, the left and right cursor keys, or the left and right tool buttons. You can go back to a file you have already measure and add or change existing measurements there. 21. Periodically (and before you quit) make sure you save the measurement file using Save Measurements. This is an XML text file with an obvious structure that is suitable for reading into your favourite analysis package. Both R and Matlab habe XML reading facilities, or you can read it into Excel and export as CSV if you prefer. Cloud Digitiser Manual 15