Software to compute 3D metrics given 3D models from satellite imagery.
-------------- 
| Basic Info |
--------------
There are 6 relevant folders:
- 'data_example': Sample data to demo the metrics pipeline, it contains input data, and ground truth data
- 'pipeline25D': metrics to estimate volumetric overlap with ground truth data.
- 'pipelinePCS': metrics to estimate positioning accuracy, completeness, 3D surface and curvature fidelity
- 'pipelineVectors': Lidar-free vertical and horizontal RMS error calculation
- 'Registration': Performs the registration of meshes to ground truth lidar mesh and reports relative offset.
- '3rdparty': All dependencies are included in this folder

------- 
| Run |
-------
>>run_example
This is an example script to walk you through the inputs needed. 
Flow:
-----------------------------	  -----------------------------     --------------     -------------------     ---------------
| Read Input point cloud/mesh| ==>| Registration: X,Y,Z offset| ==> |2.5D metrics| ==> | Vectors metrics | ==> | PCS metrics |
-----------------------------     -----------------------------     --------------     -------------------     ---------------
It runs all three metric types sequentially after the registration component. 

Alternatively, you can run each separate metric as well:
1) 2.5D Metrics
-----------------------------	  -----------------------------     --------------
| Read Input point cloud/mesh| ==>| Registration: X,Y,Z offset| ==> |2.5D metrics|
-----------------------------     -----------------------------     --------------
Usage:
[metrics2D,  metrics3D] = pipeline25D_run(files25D, params25D);
Input: 
+Files25D:
	-DSM file Ground truth
	-DTM file Ground truth
	-AOI Mask Ground truth, mask with layout of features of interest produced by LIDAR ground truth data
	-AOI Mask of algorithm to measure, mask with layout of features of interest produced by the algorithm
	-File with registration offsets to be applied
+params25D:
	- configuration parameters. See run_example.m for example values
Output:
%   metrics2D    - 2D metrics results
%   metrics3D    - 3D metric results

2) vector metrics
-----------------------------	  -----------------------------     -----------------
| Read Input point cloud/mesh| ==>| Registration: X,Y,Z offset| ==> |Vectors metrics|
-----------------------------     -----------------------------     -----------------
Usage: 
[hrms,hrms_uncertainty, vrms,vrms_uncertainty] = vector_metrics_run(data_filename,aoi_filename,bldg_filename,road_filename,params);
Input: 
+data_filename: input pointcloud/mesh produced by the algorithm to measure
+aoi_filename: kml file with layout of area
+bldg_filename: kml file with boundaries of AOIs for horizontal rmse calculation
+road_filename: kml file with road markings for vertical rmse calculation
+params:
	- configuration parameters. See run_example.m for example values
	
Output: 
+hrms: horizontal rms error result
+hrms uncertainty: horizontal rms error uncertainty result
+vrms: vertical rms error result
+vrms uncertainty: vertical rms error uncertainty result

3) Positional, curvature and surface metrics
-----------------------------	  -----------------------------     -------------
| Read Input point cloud/mesh| ==>| Registration: X,Y,Z offset| ==> |PCS metrics|
-----------------------------     -----------------------------     -------------
Usage:
[outmesh] = PCSmetric_run(meshinput,referencepcpath,gtAOIpath,pointspacing,registration_done,visualflag,fid);
Input: 
+ meshinput: data structure with mesh information
	- estimated gsd: input gsd (estimated)
	- triangle_node: face information - vertex connectivity
	- Nfaces: number of faces
	- node_xyz: array with vertex 3D coordinates
	- Nnodes: number of vertices
	- filenameLAS: file location of input las file where input mesh is written 
	- lasobject: las data structure
+ referencepcpath: lidar ground truth file location
+ gtAOIpath: AOI mask file location
+ pointspacing: ground truth lidar point spacing
+ registration_done: flag to indicate whether input file has been registered with respect to ground truth
+ visualflag: flag for plotting results
+ fid: file handle for report results

Output:
+ outmesh: data structure containing all metric results

-------------------------------
| Requirements & Dependencies |
-------------------------------
You'll need a C++ compiler to build some internal mex files.
Systems tested on:
Windows7 16GB RAM (minimum required) 
Visual Studio 10, 12, 13
Matlab2015b or newer
Matlab toolboxes needed: image_toolbox, map_toolbox

Dependencies:
'lldeg' utility: converts UTM coordinates to Lat/Lon coordinates and viceversa
'ransac': package to run robust estimator RANSAC
'lasdata': script to read 'las' files
'writeply' and 'write_mesh2ply': scripts to write meshes in 'ply' format
'subdivide_tri': utility to subdivide a mesh using triangular subdivision

To run on a Linux system:
Registration code needs to be built in linux environment. Check instructions inside Registration folder for how-to.

---------------- 
| Ground Truth |
----------------


If you use this software and/or data please cite the following paper:
- M. Bosch, A. Leichtman, D. Chilcott, H. Goldberg, M. Brown, 
"METRIC EVALUATION PIPELINE FOR 3D MODELING OF URBAN SCENES",
 International Archives of the Photogrammetry, Remote Sensing and 
Spatial Information Sciences, Volume XLII-1/W1, 2017.

% Copyright 2017 The Johns Hopkins University Applied Physics Laboratory.
% Licensed under the MIT License. See LICENSE.txt in the project root for full license information.