Matlab toolbox for creating 3D cave models from sparse survey
pmls4matlab is the proof of concept implementation of the applied surface reconstruction technique in our novel 3D cave surveying method: Poor Man’s Laserscanner (PMLS): a simple method of 3D cave surveying. Our method is based on sparse measurements performed with Beat Heeb’s DistoX or similar laser distance meter equipped with compass and inclinometer. We can capture very few samples with the Disto compared to point clouds resulting from Terrestrial Laser Scanners (TLS) or GeoSlam’s ZEB1/ZEB REVO handheld laser scanners. In addition, the distribution of the sampled points can be extremely uneven, while caves usually have layouts with lots of features at all scales. To overcome these difficulties a robust and reliable surface reconstruction algorithm had to be developed. The proposed sofware, pmls4matlab interpolates the measured points with a watertight surface, which is free of self-intersections. We have found that even complicated geometric layouts can be recovered with good detail from as few as 50 to 150 splay shots per station. More technical details can be found in our paper.
Change to a directory in which the PMLS system will be installed. A new directory called “pmls4matlab” will be created in which pmls4matlab will be set up.
git clone https://github.com/poormanslaserscanner/pmls4matlab.gitcd pmls4matlab
git submodule update --initcd ..
cd(getenv('PMLS_INSTALL_DIR'))setup
xyz then the name of the corresponding survey CSV file is xyz.csv .csv.)It is always assumed that there is a station with identifier 0 and cartesian coordinates [0,0,0]. The shots whith both From station and To station identifiers compose the network of the stations. This network cannot be disconnected and so the cartesian coordinates of all the stations can be derived from the shots and from the location of station 0. There can be multiple shots with the same from and to stations. In that case we will take the average of the readings. The network may also contain loops, in which case we shall optimally distribute the errors on the measurements.
A shot without a To station is called a splay shot and is assumed to be a point on the cave’s wall. Stations are not necesarily on the wall, shots can also be made from a tripod. If a station is on the wall, it is recommended to take a so called zeroshot. A zeroshot is a shot without a distance but with normal direction to the wall. zeroshots have identical From station and To station identifiers in the CSV. Only stations with zeroshots will be assumed to be on the wall.
H = plgetinput(csvname,n);
Will read the survey data from the csvname main CSV file and the refered survey CSV files. The stations with fewer splay shots than n will be ignored (they will be used in determining the location of the stations, but they will not be used for surface reconstruction). A typical value of n is between 5 and 10.
H = plgetinput(csvname,n,poligonname);
poligonname is the name of a .cave file. This file format is used by the poligon software, which is the most widely used cave surveying program in Hungary. In that format the function will first read in the stations defined in the poligonname file.
The output H is a special struct that will be used in the further steps. We will call this internal data structure plstruct
M = pmlsrecon(H, vox1, vox2, ...);
Outlier measurements will be automatically removed and the surface reconstruction will be done based on the remaining shots. The reconstruction is performed in several steps starting with a coarser step followed with steps trying to recover finer details. The number of the vox1, vox2,... parameters determines the number of steps and the values give the level of detail in voxel size for the corresponding steps. Voxel sizes should be given in centimeters. In the case of the test data sets for Speizi and Ferenc
M = pmlsrecon(H, 4, 3);
For Legeny:
M = pmlsrecon(H, 6, 5);
is a good choice. Note that run times will be long. It can take several hours. Temporary files will be created in the subdirectory pltmp. The output M will be a plstruct with the resulting mesh and the input data without the outliers.
plsave(filename, S);
Saves plstruct S to filename. filename will be a .mat file.
plload(filename);
Loads plstruct from filename to the current matlab workspace with the name it was saved.
The resulted mesh can be exported into Stanford Polygon format.
plexport(filename, M);
The content of the plstruct M will be exported. The mesh will be saved in filename.ply. The input survey will exported to filename.dxf.
PMLS is a group endeavor of a few cavers from Hungary. You can hu@cave3d.org">contact us if you have questions or comments.
If you’re using our work, please drop us a note to justify spending time maintaining this.
Copyright 2014-2017 Attila Gáti.
If you publish a work, in which you have used PMLS you could cite:
Attila Gáti, Nikolett Rehány, Balázs Holl, Zsombor Fekete and Péter Sűrű:
“The Poor Man’s Laser Scanner: a Simple Method of 3D Cave Surveying”
CREG-Journal 96, pp. 8—14, 2016
pmls4matlab is licensed under the GNU GENERAL PUBLIC LICENSE version 3.
Our software is heavily based on other’s work:
Fang, Qianqian, and David A Boas. 2009. “Tetrahedral Mesh Generation
from Volumetric Binary and Grayscale Images.” In 2009 Ieee
International Symposium on Biomedical Imaging: From Nano to Macro,
1142–5. IEEE. http://iso2mesh.sourceforge.net/cgi-bin/index.cgi.
Hang Si. 2015. ”TetGen, a Delaunay-Based Quality Tetrahedral Mesh Generator”. ACM Trans. on Mathematical Software. 41 (2), Article 11 (February 2015), 36 pages. http://doi.acm.org/10.1145/2629697.
M. Attene. 2010. ”A lightweight approach to repairing digitized polygon meshes”. The Visual Computer, (c) Springer. DOI: 10.1007/s00371-010-0416-3
Heeb, Beat. 2009. “An All-in-One Electronic Cave Surveying Device.”
CREG-Journal, no. 72. BCRA:8–10.
http://bcra.org.uk/pub/cregj/index.html?j=72.
———. 2014. “The Next Generation of the DistoX Cave Surveying
Instrument.” CREG-Journal, no. 88. BCRA:5–8.
http://bcra.org.uk/pub/cregj/index.html?j=88.