# About Compass 2.0

Compass is a structural geology toolbox for the interpretation and analysis of virtual outcrop models. It combines a flexible data structure for organising geological interpretation with a series of tools for intuitive and computer-assisted digitisation and measurement. Broadly, the tool comprises two modes: Map Mode, for delineating geological units, and Compass Mode for measuring orientations and thicknesses. Additionally, topological features such as crosscutting relationships and younging directions can also be defined and stored for later analysis. The combination of these two modes roughly correspond to the functionality of a good field geologist (armed with a trusty compass and notebook), but require less beer and sunscreen. They are described in detail below.

## Compass Mode: Extracting structural measurements

The compass mode, activated by clicking the "compass" icon in the main dialog, contains three tools for measuring orientations: the Plane Tool, Trace Tool and Lineation Tool. A self-explanatory Picking Tool is also included for convenience.

### Plane Tool: Measure surface orientations

The plane tool is used to measure the orientations of fully exposed planar structures, such as joint or bedding surfaces. When it is activated, a red circle is shown in the 3D window. On picking a point in the virtual outcrop model (left-click), a plane is fitted to all points sitting within the circle (using least squares), giving an orientation estimate (dip/dip direction). The circle radius can be changed with ctrl-scroll wheel. Note that for this to work correctly, Cloud Compare needs to be using orthographic projection (Display->Toggle Centred Perspective).

### Trace Tool: Digitise and measure traces and contacts

The trace tool allows the estimation of a structure or contact's orientation based on its intersection with a non-flat surface. It uses a least-cost path algorithm to 'follow' these intersection traces along the surface between user defined start and end points, and then calculates the best fit plane to estimate the orientation. To use, select the tool and then left click the start and end of the structure you would like to digitise/measure. The tool will then try to find a fracture trace that links these points. Generally this works remarkably well, though, intermediate 'waypoints' can be added (also using left click) to modify the trace. To finish a segment click 'Accept' (green tick) or press the Space Key. To cancel a segment, click 'Close' or press the Escape key.

The results of this tool depend on the cost function used by the least-cost path algorithm. A variety of these have been implemented, and can be activated by clicking the algorithm dropdown (settings icon). The different cost functions that have been implemented are:

- Darkness [default] - traces follow dark points in the cloud. This is good for fracture traces defined by shadow.
- Lightness - traces follow light points in the cloud. This is good for light-coloured structures such as veins.
- RGB - traces avoid colour contrasts, following points with a similar colour to the start and end points.
- Curvature - traces follow points on ridges and valleys. This can be good for fracture traces with high relief. Note that for performance reasons, the tool will pre-compute a scalar field describing the curvature. This can be slow for large datasets.
- Gradient - traces follow colour boundaries such as lithological contacts. As above, the gradient will be precomputed as a scalar field, which can be slow.
- Distance - traces take the shortest path. This can be useful if you simply need "straight" lines.
- Scalar Field - traces follow low values in the active (displayed) scalar field. Use this to implement custom cost functions!
- Inverse Scalar Field - traces follow high values in the active (displayed) scalar field. Use this to implement custom cost functions!

When using this tool it is important to note that its performance (i.e. speed) scales with trace length. Hence, it can be used with large point clouds if trace lengths are kept small (though long traces can be quickly digitised as multiple segments). Asking the tool to find long traces may result in system crashes.

Once a trace has been accepted, it is replaced by the computed best-fit plane. However, the actual trace object will be stored as a child to this plane, and by selecting it (with the Trace Tool active), modifications can be made as desired. Also note that if the points on the trace are approximately co-linear (i.e. there is not enough topography to provide a good orientation estimate) the fit-plane is automatically rejected and the trace object kept as-is for reference/further editing. Furthermore, if the point cloud being interpreted has previously calculated point normals, best-fit planes are also rejected if they fall within 10 degrees of the average surface orientation along the trace.

Automatic plane fitting can be enabled/disabled (it is disabled by default) in the algorithm menu (settings icon) or holding the shift key when accepting the trace. Plane orientations are expressed using the dip/dip direction convention.

### Lineation Tool: Measure lineations

This tool measures the length, trend and plunge of a (straight) line between two points. Left-click selects points (as above).

## Map Mode

Map Mode provides functionality for storing and organising interpretations in larger projects, where many different geological features need to be recorded. On entering Map Mode (map icon), a second dialog contains functionality for creating and managing GeoObjects appears. GeoObjects are a data structure for organising and describing geological features in a flexible way, and are comprised of an Interior, Upper Boundary and Lower Boundary. Hence, measurements from a dyke for example, can be assigned such that they are representative of either contact (somewhat arbitrarily called upper and lower) or the interior. The GeoObject dialog contains functionality for creating GeoObjects and defining their active part (upper, lower or interior), to which any new measurements get assigned.

When Map Mode is active, the Compass functionality described above remains as described above with a few subtle difference. As already mentioned, new measurements are stored in the active GeoObject rather than in a Measurements folder. Furthermore, traces defined using the Trace tool are also kept visible in this mode (rather than converted to planes), so the Trace tool can be used to digitise contacts.

## Other Tools

The Other Tools dropdown (Plus icon) contains additional functionality, and includes tools for measuring true thicknesses, recording notes and exporting interpretation for 2D visualisation. These Other Tools are summarised in the order they appear below.

### Add Pinch Node

Pinch nodes are used to record locations were the upper and lower surfaces of a GeoObject meet, such as at dyke tips or were sedimentary layers pinch-out. Pinch nodes are simply represented by a single point, but in being assigned to a GeoObject can record important information.

### Measure One-Point/Two-Point Thickness

The Measure One-Point Thickness and Measure Two-Point Thickness tools can be used to measure the true-thickness of geological units by selecting a plane representing the orientation of a unit and one or two points on its boundary. Measure One-Point Thickness will measure the plane-perpendicular distance between the selected plane and each successively chosen points (use this if the fit-plane represents one of the contacts). Measure Two-Point Thickness measures the plane-perpendicular distance between pairs of successively chosen points (used when the fit-plane doesn't fall on one of the contacts).

### Add note

The Add Note tool allows short notes to be placed on a point cloud. After activating this tool, left-click on the location the note should be associated with and a prompt should appear, in which the note can be added. As always, short notes are best.

### Fit Plane to GeoObject

On some occasions, a GeoObject comprised of multiple different trace objects will define a well-constrained plane. As the trace-tool only allows plane-fitting to an individual trace, the Fit Plane to GeoObject tool will calculate a fit plane for all traces defining the upper and lower surfaces of a GeoObject. Use with care, as this can often produce spurious results.

### Estimate Structure Normals

This tool uses a combines a bayesian plane fitting algorithm with a moving window search algorithm to (1) identify the best constrained fit plane for each point in a structural trace and (2) generate orientation estimates using an MCMC sampler. These provide estimates of a structures orientation at each point along a trace, and associated uncertainty. Please refer to the documentation on the CloudCompare wiki page for further details regarding this tool.

### Merge selected GeoObjects

Merges all of the GeoObjects selected in the DB Tree into the currently active (most recently selected) GeoObject.

### Export SVG

Exports trace objects to a .svg file for "beautification" in vector-graphics packages such as Inkscape or Adobe Illustrator. Traces will projected into 2D using the current view-direction and camera settings, so should appear as viewed on the screen. Other objects (e.g. point clouds) can be included by rendering an image with standard CloudCompare functionality (Display->Render to File)

## Saving and Exporting Measurements

Interpretation generated using this tool is represented internally by standard planes and polygons, and so can be natively stored in CC's .bin files. Each time the plugin is loaded it searches the CloudCompare database to look for any custom Compass objects, so interpretations can be saved and retrieved from disk, provided Compass is restarted (closed and then re-opened) each time new .bin files are loaded.

For ease of use, an export tool has also been included. This tool exports plane, trace and lineation data to .csv files, from which data can be easily imported into other software packages for further analysis. The GeoObject data structure is encoded via the object names. For more complex analysis data can also be exported to a .xml file format that preserves the complete structure of a CloudCompare project. Polylines created by the Trace and Lineation tools can also be exported as shapefiles through the normal save dialog.

## Further Reading and Citation

If you found this tool useful, please cite Thiele et al., 2017. The publication contains a more detailed description of the methods employed by this plugin.

Thiele, S. T., Grose, L., Samsu, A., Micklethwaite, S., Vollgger, S. A., and Cruden, A. R.: Rapid, semi-automatic fracture and contact mapping for point clouds, images and geophysical data, Solid Earth Discuss., https://doi.org/10.5194/se-8-1241-2017, 2017