CAPOC Cave Point Clouds (and Meshes)

Capoc (Cave Point Clouds and Meshes) is a tool for immersive browsing of 3D cave models, registering models and taking virtual measurements from within the model.

This tutorial serves as documentation of Capoc until something better is written. Since the browsing function is rather intuitive, it focuses on registration (ie. aligning a SfM model with a real-world cave survey polygon) and taking virtual measurements.

Loading and aligning models

Download and extract capoc

Download capoc-windows.zip and extract it to a convenient location. Capoc does not need installing.

Download and extract example data

Download the example data coming along with this tutorial: capoc-example.zip. Extract the archive contents to a convenient location.

Load the SfM model

Open the top menu and select File / Open model. Select the sfm_cave.ply from the example data set.

Load camera poses

Again go to the top menu, this time selecting File / Open NVM. Choose the NVM file example.nvm from the nvm subdirectory of the example data set

Browse through images

If you click on Images in the left pane of the main window, a list of files should appear. Double click the first file P8172450.JPG. A photograph from our example cave should appear in the right pane.

See relations between images and 3D

Now right click the image file name and select Assume pose

Browse the 3D model

You should see a 3D view of the cave. Holding left mouse key pressed, drag mouse around the window to change viewing angles. You can also use a/s/d/w keys to navigate the model. If you step back (pressing s), you will notice the model is actually upside down. To fix it, we will align the model to a real world cave survey, locating four survey stations on the SfM photographs.

Find the survey station

Again double click the image file name. Notice the survey station marking on a rock in the bottom right corner of the picture. Using right mouse button, drag the red cross onto this marking. Then press and hold shift, and holding the key right-drag so that the range indication (the circle around the cross) is only slightly bigger than the cross itself.

Find 3D points in the model

Now go to the top menu and select NVM / Reproject pixel

Verify the point was found

If all goes well, the cursor will turn green and the status bar at the window bottom should indicate some 3D coordinates. After the reprojection, the cursor might move slightly or stay in the same place. At this stage, either is fine.

If it is not the case and the status bar reads Reprojection failed, you need to reposition the cursor - and probably increase the reprojection range (ie. make the circle around cursor bigger). After that, select NVM / Reproject pixel again.

Save the point

Now go to the left pane of the main window and find the sfm_cave file within the Models group. Right-click the file name to open a menu. Select Add point.

Assign a name

In the newly open window, name this point dep.1 (the name is very important). Click OK to save the point.

Find and mark dep.0

Double click P8172466.JPG. Locate the "0" point marking (near the middle of right edge). Move the reprojection cursor to this point (with right-dragging). Again use NVM / Reproject pixel and Add point to find and store 3D coordinates. Store this point as dep.0

Find and mark dep.2

You need at least four points to define an affine transformation, so still two to go. Double click P8172482.JPG and notice another surveying station near the middle of the top edge. Reproject this point and save it as dep.2

Find and mark dep.3

The last example point is located on P8172975.JPG. There is a small "3" on the rock not far from the bottom left corner. Reproject this point and save it as dep.3

Load cave survey

Use File / Open model... and load the cave survey file from svx subdirectory (the filename is dep.3d). This file contains real world coordinates for surveying stations.

Now if you browse the point list, it will become clear why the point names were so important: the names we had used match exactly the station names occuring in dep.3d

Select the master model

Right click dep.3d in the left pane. When a menu opens, select Set as master. This lets capoc know which of the loaded models is the real world (in terms of coordinate systems).

Compute transform

Now right click sfm_cave.ply and select Transform / Transform to master

Enjoy aligned model

Seemingly nothing interesting happened. However, right click P8172466.JPG and select Assume pose. You will see that the cave model is now rotated and scaled to match the imported survey.

View log

Click View / Message log to see more detailed information on the transformation process.

Worth knowing

Capoc can open PLY, OFF, NVM and Survex 3D files. You can "load" a NVM file as a model. In that case, of course only the sparse point cloud is loaded (no mesh).
The plane fitting works on points, it does not need a mesh (and does not use any surface information)
The first loaded model is special to Capoc. Only one NVM file can be loaded at a time and it is always assigned to the first model. Also, points can only be selected from the first model.
Reproject pixel projects the model vertices onto currently selected camera plane. Comparing to what SfM does, this is the backward direction and hence the feature name. If less than five mesh points end up within the cursor range (red circle), the 3D point closest to camera is selected and indicated in green both on 3D views and the image view. If five or more matching points are found,
With File / Save project you can create a script that will load your current models, enter all saved points and set the camera at the current position. If you restart Capoc, this script can be then loaded through File / Execute script...

Measurements with Capoc

Go to cross-section view

Select View / Xsect. Zoom in using the = key (or View / Zoom in a couple of times). Right click somewhere on the cross section and drag the mouse, holding right mouse button pressed - a straight line will appear. This is how simple virtual measurements in Capoc are made. You can see the line length and orientation on the status bar (bottom of the window).

Select points

Now press and hold Shift. With Shift pressed, right click somewhere on the wall within the cross-section and holding both the right mouse button and shift, drag the mouse. With this action, a piece of the 3D model is marked with yellow colour.

Explore the selection

Select View / Caver. If you back away a little (with s key), you will notice the selection is also visible on the perspective view.

Fit plane to selection

Now we will measure the average orientation of the selected part of the model. Right-click sfm_cave.ply. Select Selection / Fit plane.

Read measurements

The fitted plane is indicated on the 3D view with randomly scattered blue dots and a blue line representing the normal vector. Verify if makes sense, and if so, take notice of the readings visible on status bar.

Worth knowing

There is an extensive scripting system available in Capoc. Check File / Console. Commands are entered in the lower text box. Context help is available by typing a question mark (start with just typing a single question mark - ?). You can also write down commands into a text file and execute them with File / Execute script.