Adaptive Multigrid Solvers (Version 15.01)

For efficiency, the code is designed to compile for the specific FEM degree and boundary condition specified in PoissonRecon.h. (Specifically, DEFAULT_FEM_DEGREE is set to 1 and DEFAULT_FEM_BOUNDARY is set to Neumann.) You can change the default values in PoissonRecon.h. You can also compile the code so that it supports varying FEM degrees and boundary conditions by un-#define-ing FAST_COMPILE in PreProcess.h. However, this will make the compilation significantly slower.
By default, the implementation assumes that all indexing can be done with 32-bit integers. If you are reconstructing large scenes and need more bits for indexing, you should enable the BIG_DATA flag in PreProcessor.h. Note that if the generated mesh has more primitives than can be indexed by a 32-bit integer, the output .ply file will store the integers using 64-bit precision (designated by the long long type) instead of the standard 32-bit precision (designated by the int type). Note that this is not a standard format and software like MeshLab may not be able to read the file.
The distributed PSR code uses sockets for communication between the client and the server. These are supported in a cross-platform way via Boost. (The code was developed and tested under Boost version 1.80.0.)
To support reading/writing images, the code requires installation of the zlib, png, and jpg libraries. Source code for these is included for compilation using Visual Studios. The Makefile assumes that the header files can be found in /usr/local/include/ and that the library files can be found in /usr/local/lib/.

EXECUTABLES

--in <input points>: This string is the name of the file from which the point set will be read.
If the file extension is .ply, the file should be in PLY format, giving the list of oriented vertices with the x-, y-, and z-coordinates of the positions encoded by the properties x, y, and z and the x-, y-, and z-coordinates of the normals encoded by the properties nx, ny, and nz .
If the file extension is .bnpts, the file should be a binary file, consisting of blocks of 6 32-bit floats: x-, y-, and z-coordinates of the point's position, followed by the x-, y-, and z-coordinates of the point's normal. (No information about the number of oriented point samples should be specified.)
Otherwise, the file should be an ascii file with groups of 6, white space delimited, numbers: x-, y-, and z-coordinates of the point's position, followed by the x-, y- and z-coordinates of the point's normal. (No information about the number of oriented point samples should be specified.)
[--envelope <constraint envelope>]: This string is the name of the file from which the constraint envelope will be read.
The file should be a water-tight triangle mesh in PLY format, oriented so that the normals are pointing in the direction that should be outside of the reconstructed surface.
[--out <output triangle mesh>]: This string is the name of the file to which the triangle mesh will be written. The file is written in PLY format.
[--tree <output octree and coefficients>]: This string is the name of the file to which the the octree and solution coefficients are to be written.
[--grid <output grid>]: This string is the name of the file to which the sampled implicit function will be written. The file is written out in binary, with the first 4 bytes corresponding to the (integer) sampling resolution, 2^d, and the next 4 x 2^d x 2^d x ... bytes corresponding to the (single precision) floating point values of the implicit function.
[--degree <B-spline degree>]: This integer specifies the degree of the B-spline that is to be used to define the finite elements system. Larger degrees support higher order approximations, but come at the cost of denser system matrices (incurring a cost in both space and time).
The default value for this parameter is 1.
[--bType <boundary type>]: This integer specifies the boundary type for the finite elements. Valid values are:

1: Free boundary constraints
2: Dirichlet boundary constraints
3: Neumann boundary constraints
The default value for this parameter is 3 (Neumann).
[--depth <reconstruction depth>]: This integer is the maximum depth of the tree that will be used for surface reconstruction. Running at depth d corresponds to solving on a grid whose resolution is no larger than 2^d x 2^d x ... Note that since the reconstructor adapts the octree to the sampling density, the specified reconstruction depth is only an upper bound.
The default value for this parameter is 8.
[--width <finest cell width>]: This floating point value specifies the target width of the finest level octree cells.
This parameter is ignored if the --depth is also specified.
[--scale <scale factor>]: This floating point value specifies the ratio between the diameter of the cube used for reconstruction and the diameter of the samples' bounding cube.
The default value is 1.1.
[--samplesPerNode <minimum number of samples>]: This floating point value specifies the minimum number of sample points that should fall within an octree node as the octree construction is adapted to sampling density. For noise-free samples, small values in the range [1.0 - 5.0] can be used. For more noisy samples, larger values in the range [15.0 - 20.0] may be needed to provide a smoother, noise-reduced, reconstruction.
The default value is 1.5.
[--pointWeight <interpolation weight>]: This floating point value specifies the importance that interpolation of the point samples is given in the formulation of the screened Poisson equation.
The results of the original (unscreened) Poisson Reconstruction can be obtained by setting this value to 0.
The default value for this parameter is twice the B-spline degree.
[--iters <Gauss-Seidel iterations per level>]: This integer value specifies the number of Gauss-Seidel relaxations to be performed at each level of the octree hierarchy.
The default value for this parameter is 8.
[--density]: Enabling this flag tells the reconstructor to output the estimated depth values of the iso-surface vertices.
[--normals]: Enabling this flag tells the reconstructor to output vertex normals, computed from the gradients of the implicit function.
[--colors]: If the input points are in ASCII/binary format and contain color values, this flag lets the reconstruction code know that (1) each sample is represented by nine floating point values instead of the expected six, and that (2) color values should be output with the vertices of the reconstructed surface. (For input samples in the .ply format, the presence of color information, as well as any other additional per-sample data, is automatically determined from the file header.)
[--data <pull factor>]: If the input points have additional data (e.g. color) that is to be sampled at the output vertices, this floating point value specifies the relative importance of finer data over lower data in performing the extrapolation.
The default value for this parameter is 32.
[--confidence <normal confidence exponent>]: This floating point value specifies the exponent to be applied to a point's confidence to adjust its weight. (A point's confidence is defined by the magnitude of its normal.)
The default value for this parameter is 0.
[--confidenceBias <normal confidence bias exponent>]: This floating point value specifies the exponent to be applied to a point's confidence to bias the resolution at which the sample contributes to the linear system. (Points with lower confidence are biased to contribute at coarser resolutions.)
The default value for this parameter is 0.
[--primalGrid]: Enabling this flag when outputing to a grid file has the reconstructor sample the implicit function at the corners of the grid, rather than the centers of the cells.
[--linearFit]: Enabling this flag has the reconstructor use linear interpolation to estimate the positions of iso-vertices.
[--polygonMesh]: Enabling this flag tells the reconstructor to output a polygon mesh (rather than triangulating the results of Marching Cubes).
[--tempDir <temporary output directory>]: This string is the name of the directory to which temporary files will be written.
[--threads <number of processing threads>]: This integer specifies the number of threads across which the algorithm should be parallelized.
The default value for this parameter is equal to the numer of (virtual) processors on the executing machine.
[--maxMemory <maximum memory usage (in GB)>]: If positive, this integer value specifies the peak memory utilization for running the reconstruction code (forcing the execution to terminate if the limit is exceeded).
[--performance]: Enabling this flag provides running time and peak memory usage at the end of the execution.
[--verbose]: Enabling this flag provides a more verbose description of the running times and memory usages of individual components of the surface reconstructor.

--in <input points>: This string is the name of the file from which the point set will be read.
The file is assumed to be in binary PLY format, giving the list of oriented vertices with the x-, y-, and z-coordinates of the positions encoded by the properties x, y, and z and the x-, y-, and z-coordinates of the normals encoded by the properties nx, ny, and nz. (If additional properties, e.g. color, are provided per sample, these will be interpolated in the reconstruction.)
--tempDir <networked temporary output directory>: This string is the name of the directory to which temporary files will be written.
The specified (networked) path is assumed to accessible to the server and all clients.
--out <output polygon mesh>: This string is the name of the file to which the polygon mesh will be written.
The file is written in PLY format.
--count <client count>: This integer values specifies the number of clients that will be connecting to the server to peform the partitioning.
[--port <listening port>]: This optional integer specifies the port at which the server should listen for client requests.
If no port is specified, the server will ask the system to provide one.
Regardless of verbosity value, the server will print out the address and port to the command line.
[--depth <reconstruction depth>=8]: This integer is the maximum depth of the tree that will be used for surface reconstruction. Running at depth d corresponds to solving on a grid whose resolution is no larger than 2^d x 2^d x ... Note that since the reconstructor adapts the octree to the sampling density, the specified reconstruction depth is only an upper bound.
[--pDepth <partition/server depth>=5]: This integer is the depth of the tree at which the server performs the reconstruction and is also the depth at which the partitioning of the points happens. Running at a partition/server depth d corresponds to having the server solve over a grid whose resolution is 2^d x 2^d x ... and partitions the point set into 2^d slabs.
[--width <finest cell width>]: This floating point value specifies the target width of the finest level octree cells.
This parameter is ignored if the --depth flag is also specified.
[--degree <B-spline degree>=1]: This integer specifies the degree of the B-spline that is to be used to define the finite elements system. Larger degrees support higher order approximations, but come at the cost of denser system matrices (incurring a cost in both space and time).
This option is only available if the code is compiled without the FAST_COMPILE flag #define-ed.
[--bType <boundary type>=3]: This integer specifies the boundary type for the finite elements. Valid values are:

1: Free boundary constraints
2: Dirichlet boundary constraints
3: Neumann boundary constraints
This option is only available if the code is compiled without the FAST_COMPILE flag #define-ed.
[--scale <scale factor>=1.1]: This floating point value specifies the ratio between the diameter of the cube used for reconstruction and the diameter of the samples' bounding cube.
[--samplesPerNode <minimum number of samples>=1.5]: This floating point value specifies the minimum number of sample points that should fall within an octree node as the octree construction is adapted to sampling density. For noise-free samples, small values in the range [1.0 - 5.0] can be used. For more noisy samples, larger values in the range [15.0 - 20.0] may be needed to provide a smoother, noise-reduced, reconstruction.
[--pointWeight <interpolation weight>=2*<B-spline degree>]: This floating point value specifies the importance that interpolation of the point samples is given in the formulation of the screened Poisson equation.
The results of the original (unscreened) Poisson Reconstruction can be obtained by setting this value to 0.
[--iters <Gauss-Seidel iterations per level>=8]: This integer value specifies the number of Gauss-Seidel relaxations to be performed at each level of the octree hierarchy.
[--density]: Enabling this flag tells the reconstructor to output the estimated depth values of the iso-surface vertices.
[--data <pull factor>=32]: If the input points have additional data (e.g. color) that is to be sampled at the output vertices, this floating point value specifies the relative importance of finer data over lower data in performing the extrapolation.
[--confidence <normal confidence exponent>=0]: This floating point value specifies the exponent to be applied to a point's confidence to adjust its weight. (A point's confidence is defined by the magnitude of its normal.)
[--confidenceBias <normal confidence bias exponent>=0]: This floating point value specifies the exponent to be applied to a point's confidence to bias the resolution at which the sample contributes to the linear system. (Points with lower confidence are biased to contribute at coarser resolutions.)
[--verbose <verbosity>=0]: This integer value specifies the level of verbosity of output provided by the client and server, with "0" corresponding to no output and "4" giving the most.
[--linearFit]: Enabling this flag has the reconstructor use linear interpolation to estimate the positions of iso-vertices.
[--threads <number of processing threads>={number of (virtual) processors on the executing machine}]: This integer specifies the number of threads across which the algorithm should be parallelized.
[--maxMemory <maximum memory usage (in GB)>]: If positive, this integer value specifies the peak memory utilization for running the reconstruction code (forcing the execution to terminate if the limit is exceeded).
The default value for this parameter is 0.
[--performance]: Enabling this flag provides running time and peak memory usage at the end of the execution.
[--noFuse]: Enabling this flag keeps the server from fusing shared vertices across slabs. (The reconstructions from the different clients will still be merged into a single .ply file.)

--port <server port>: This integer specifies the port at which to connect to the server.
[--address <server address>="127.0.0.1"]: This optional string specifies the IPv4 address of the server.
[--multi <sub-client multiplicity>=1]: This optional integer specifies the number of sub-clients the client should be running serially.
[--threads <number of processing threads>={number of (virtual) processors on the executing machine}]: This integer specifies the number of threads across which the algorithm should be parallelized.
The default value for this parameter is equal to the numer of (virtual) processors on the executing machine.
[--maxMemory <maximum memory usage (in GB)>=0]: If positive, this integer value specifies the peak memory utilization for running the reconstruction code (forcing the execution to terminate if the limit is exceeded).
[--pause]: Enabling this flag has the client wait for the user to enter [ENTER] before closing the process. (Useful if the client is opened in a temporary window, you are running the client with verbose output, and want to see the output.)

--in <input points>: This string is the name of the file from which the point set will be read.
If the file extension is .ply, the file should be in PLY format, giving the list of oriented vertices with the x-, y-, and z-coordinates of the positions encoded by the properties x, y, and z and the x-, y-, and z-coordinates of the normals encoded by the properties nx, ny, and nz .
If the file extension is .bnpts, the file should be a binary file, consisting of blocks of 6 32-bit floats: x-, y-, and z-coordinates of the point's position, followed by the x-, y-, and z-coordinates of the point's normal. (No information about the number of oriented point samples should be specified.)
Otherwise, the file should be an ascii file with groups of 6, white space delimited, numbers: x-, y-, and z-coordinates of the point's position, followed by the x-, y- and z-coordinates of the point's normal. (No information about the number of oriented point samples should be specified.)
[--out <output triangle mesh>]: This string is the name of the file to which the triangle mesh will be written. The file is written in PLY format.
[--tree <output octree and coefficients>]: This string is the name of the file to which the the octree and solution coefficients are to be written.
[--grid <output grid>]: This string is the name of the file to which the sampled implicit function will be written. The file is wrtten out in binary, with the first 4 bytes corresponding to the (integer) sampling resolution, 2^d, and the next 4 x 2^d x 2^d x ... bytes corresponding to the (single precision) floating point values of the implicit function.
[--degree <B-spline degree>]: This integer specifies the degree of the B-spline that is to be used to define the finite elements system. Larger degrees support higher order approximations, but come at the cost of denser system matrices (incurring a cost in both space and time).
The default value for this parameter is 2.
[--depth <reconstruction depth>]: This integer is the maximum depth of the tree that will be used for surface reconstruction. Running at depth d corresponds to solving on a grid whose resolution is no larger than 2^d x 2^d x ... Note that since the reconstructor adapts the octree to the sampling density, the specified reconstruction depth is only an upper bound.
The default value for this parameter is 8.
[--width <finest cell width>]: This floating point value specifies the target width of the finest level octree cells.
This parameter is ignored if the --depth flag is also specified.
[--scale <scale factor>]: This floating point value specifies the ratio between the diameter of the cube used for reconstruction and the diameter of the samples' bounding cube.
The default value is 1.1.
[--samplesPerNode <minimum number of samples>]: This floating point value specifies the minimum number of sample points that should fall within an octree node as the octree construction is adapted to sampling density. For noise-free samples, small values in the range [1.0 - 5.0] can be used. For more noisy samples, larger values in the range [15.0 - 20.0] may be needed to provide a smoother, noise-reduced, reconstruction.
The default value is 1.0.
[--valueWeight <zero-crossing interpolation weight>]: This floating point value specifies the importance that interpolation of the point samples is given in the formulation of the screened Smoothed Signed Distance Reconstruction.
The default value for this parameter is 1.
[--gradientWeight <normal interpolation weight>]: This floating point value specifies the importance that interpolation of the points' normals is given in the formulation of the screened Smoothed Signed Distance Reconstruction.
The default value for this parameter is 1.
[--biLapWeight <bi-Laplacian weight weight>]: This floating point value specifies the importance that the bi-Laplacian regularization is given in the formulation of the screened Smoothed Signed Distance Reconstruction.
The default value for this parameter is 1.
[--iters <GS iters>]: This integer value specifies the number of Gauss-Seidel relaxations to be performed at each level of the hiearchy.
The default value for this parameter is 8.
[--density]: Enabling this flag tells the reconstructor to output the estimated depth values of the iso-surface vertices.
[--normals]: Enabling this flag tells the reconstructor to output vertex normals, computed from the gradients of the implicit function.
[--colors]: If the input points are in ASCII/binary format and contain color values, this flag lets the reconstruction code know that (1) each sample is represented by nine floating point values instead of the expected six, and that (2) color values should be output with the vertices of the reconstructed surface. (For input samples in the .ply format, the presence of color information, as well as any other additional per-sample data, is automatically determined from the file header.)
[--data <pull factor>]: If the input points have additional data (e.g. color) that is to be sampled at the output vertices, this floating point value specifies the relative importance of finer data over lower data in performing the extrapolation.
The default value for this parameter is 32.
[--confidence <normal confidence exponent>]: This floating point value specifies the exponent to be applied to a point's confidence to adjust its weight. (A point's confidence is defined by the magnitude of its normal.)
The default value for this parameter is 0.
[--confidenceBias <normal confidence bias exponent>]: This floating point value specifies the exponent to be applied to a point's confidence to bias the resolution at which the sample contributes to the linear system. (Points with lower confidence are biased to contribute at coarser resolutions.)
The default value for this parameter is 0.
[--primalGrid]: Enabling this flag when outputing to a grid file has the reconstructor sample the implicit function at the corners of the grid, rather than the centers of the cells.
[--nonLinearFit]: Enabling this flag has the reconstructor use quadratic interpolation to estimate the positions of iso-vertices.
[--polygonMesh]: Enabling this flag tells the reconstructor to output a polygon mesh (rather than triangulating the results of Marching Cubes).
[--tempDir <temporary output directory>]: This string is the name of the directory to which temporary files will be written.
[--threads <number of processing threads>]: This integer specifies the number of threads across which the algorithm should be parallelized.
The default value for this parameter is equal to the numer of (virtual) processors on the executing machine.
[--maxMemory <maximum memory usage (in GB)>]: If positive, this integer value specifies the peak memory utilization for running the reconstruction code (forcing the execution to terminate if the limit is exceeded).
[--performance]: Enabling this flag provides running time and peak memory usage at the end of the execution.
[--verbose]: Enabling this flag provides a more verbose description of the running times and memory usages of individual components of the surface reconstructor.

--inValues <input sample positions and values>: This string is the name of the file from which the positions and values will be read.
The file should be an ascii file with groups of Dim+1, white space delimited, numbers: the coordinates of the point's position, followed by the value at that point.
No information about the number of samples should be specified.
--inGradients <input sample positions and gradients>: This string is the name of the file from which the positions and gradients will be read.
The file should be an ascii file with groups of 2*Dim, white space delimited, numbers: the coordinates of the point's position, followed by the gradient at that point).
No information about the number of samples should be specified.
[--dim <dimension of the samples>]: This integerl value is the dimension of the samples.
The default value is 2.
[--tree <output octree and coefficients>]: This string is the name of the file to which the the octree and function coefficients are to be written.
[--grid <output grid>]: This string is the name of the file to which the sampled implicit function will be written. The file is wrtten out in binary, with the first 4 bytes corresponding to the (integer) sampling resolution, 2^d, and the next 4 x 2^d x 2^d x ... bytes corresponding to the (single precision) floating point values of the implicit function.
[--degree <B-spline degree>]: This integer specifies the degree of the B-spline that is to be used to define the finite elements system. Larger degrees support higher order approximations, but come at the cost of denser system matrices (incurring a cost in both space and time).
The default value for this parameter is 2.
[--bType <boundary type>]: This integer specifies the boundary type for the finite elements. Valid values are:

1: Free boundary constraints

2: Dirichlet boundary constraints

3: Neumann boundary constraints

The default value for this parameter is 1 (free).
[--depth <reconstruction depth>]: This integer is the maximum depth of the tree that will be used for surface reconstruction. Running at depth d corresponds to solving on a grid whose resolution is no larger than 2^d x 2^d x ... Note that since the reconstructor adapts the octree to the sampling density, the specified reconstruction depth is only an upper bound.
The default value for this parameter is 8.
[--width <finest cell width>]: This floating point value specifies the target width of the finest level octree cells.
This parameter is ignored if the --depth is also specified.
[--scale <scale factor>]: This floating point value specifies the ratio between the diameter of the cube used for reconstruction and the diameter of the samples' bounding cube.
The default value is 1.1.
[--valueWeight <value interpolation weight>]: This floating point value specifies the importance that interpolation of the samples' values is given in the fitting of the function.
The default value for this parameter is 1000.
[--gradientWeight <gradient interpolation weight>]: This floating point value specifies the importance that interpolation of the samples' gradients is given in the fitting of the function.
The default value for this parameter is 1.
This value is ignored unless gradient interpolation is specified.
[--lapWeight <Laplacian weight>]: This floating point value specifies the importance that Laplacian regularization is given in the fitting of the function.
The default value for this parameter is 0.
[--biLapWeight <bi-Laplacian weight>]: This floating point value specifies the importance that bi-Laplacian regularization is given in the fitting of the function.
The default value for this parameter is 1.
[--iters <GS iters>]: This integer value specifies the number of Gauss-Seidel relaxations to be performed at each level of the hiearchy.
The default value for this parameter is 8.
[--performance]: Enabling this flag provides running time and peak memory usage at the end of the execution.
[--verbose]: Enabling this flag provides a more verbose description of the running times and memory usages of individual components of the surface reconstructor.

--in <input triangle mesh>: This string is the name of the file from which the triangle mesh will be read. The file is read in PLY format and it is assumed that the vertices have a value field which stores the signal's value. (When run with --density flag, the reconstructor will output this field with the mesh vertices.)
--trim <trimming value>: This floating point values specifies the value for mesh trimming. The subset of the mesh with signal value less than the trim value is discarded.
[--out <output triangle mesh>]: This string is the name of the file to which the triangle mesh will be written. The file is written in PLY format.
[--smooth <smoothing iterations>]: This integer values the number of umbrella smoothing operations to perform on the signal before trimming.
The default value is 5.
[--aRatio <island area ratio>]: This floating point value specifies the area ratio that defines a disconnected component as an "island". Connected components whose area, relative to the total area of the mesh, are smaller than this value will be merged into the output surface to close small holes.
The default value 0.001.
[--polygonMesh]: Enabling this flag tells the trimmer to output a polygon mesh (rather than triangulating the trimming results).
[--removeIslands]: Enabling this flag tells the trimmer to discard small disconnected components of surface.
[--verbose]: Enabling this flag provides a more verbose description of the running times and memory usages of individual components of the surface reconstructor.

--in <input composite image> <input label image>: This pair of strings give the name of the composite image file and the associated label file.
All pixels in the composite that come from the same source should be assigned the same color in the label file.
PNG and JPG files are supported (though only PNG should be used for the label file as it is lossless).
[--out <output image>]: This string is the name of the file to which the stitched image will be written.
PNG and JPG files are supported.
[--degree <B-spline degree>]: This integer specifies the degree of the B-spline that is to be used to define the finite elements system. Larger degrees support higher order approximations, but come at the cost of denser system matrices (incurring a cost in both space and time).
The default value for this parameter is 1.
[--wScl <successive under-relaxation scale>]: This floating point value specifies the scale for the adapted successive under-relaxation used to remove ringing.
The default value 0.125.
[--wExp <successive under-relaxation exponent>]: This floating point value specifies the exponent for the adapted successive under-relaxation used to remove ringing.
The default value 6.
[--iters <GS iters>]: This integer value specifies the number of Gauss-Seidel relaxations to be performed at each level of the hiearchy.
The default value for this parameter is 8.
[--threads <number of processing threads>]: This integer specifies the number of threads across which the algorithm should be parallelized.
The default value for this parameter is equal to the numer of (virtual) processors on the executing machine.
[--maxMemory <maximum memory usage (in GB)>]: If positive, this integer value specifies the peak memory utilization for running the code (forcing the execution to terminate if the limit is exceeded).
[--performance]: Enabling this flag provides running time and peak memory usage at the end of the execution.
[--verbose]: Enabling this flag provides a more verbose description of the running times and memory usages of individual components of the image stitcher.

--in <input mesh>: This string is the name of the file from which the triangle mesh will be read. The file is assumed to be in PLY format.
[--out <output octree and coefficients>]: This string is the name of the file to which the the octree and solution coefficients are to be written.
[--degree <B-spline degree>]: This integer specifies the degree of the B-spline that is to be used to define the finite elements system. Larger degrees support higher order approximations, but come at the cost of denser system matrices (incurring a cost in both space and time).
The default value for this parameter is 1.
[--depth <edt depth>]: This integer is the maximum depth of the tree that will be used for computing the Euclidean Distance Transform. Running at depth d corresponds to solving on a grid whose resolution is no larger than 2^d x 2^d x ...
The default value for this parameter is 8.
[--scale <scale factor>]: This floating point value specifies the ratio between the diameter of the cube used for computing the EDT and the diameter of the mesh's bounding cube.
The default value is 2.
[--diffusion <diffusion time>]: This floating point value specifies the time-scale for the initial heat diffusion.
The default value is 0.0005.
[--valueWeight <zero-crossing interpolation weight>]: This floating point value specifies the importance that the EDT evaluate to zero at points on the input mesh is given.
The default value for this parameter is 0.01.
[--wScl <successive under-relaxation scale>]: This floating point value specifies the scale for the adapted successive under-relaxation used to remove ringing.
The default value 0.125.
[--wExp <successive under-relaxation exponent>]: This floating point value specifies the exponent for the adapted successive under-relaxation used to remove ringing.
The default value 6.
[--iters <GS iters>]: This integer value specifies the number of Gauss-Seidel relaxations to be performed at each level of the hiearchy.
The default value for this parameter is 8.
[--threads <number of processing threads>]: This integer specifies the number of threads across which the algorithm should be parallelized.
The default value for this parameter is equal to the numer of (virtual) processors on the executing machine.
[--maxMemory <maximum memory usage (in GB)>]: If positive, this integer value specifies the peak memory utilization for running the code (forcing the execution to terminate if the limit is exceeded).
[--performance]: Enabling this flag provides running time and peak memory usage at the end of the execution.
[--verbose]: Enabling this flag provides a more verbose description of the running times and memory usages of individual components of the EDT computation.

--in <input tree and coefficients>: This string is the name of the file from which the tree and implicit functions coefficients are to be read.
[--samples <input sample positions>]: This string is the name of the file from which sampling positions are to be read.
The file should be an ascii file with groups of Dim white space delimited, numbers giving the coordinates of the sampling points' position.
No information about the number of samples should be specified.
[--grid <output value grid>]: This string is the name of the file to which the sampling of the implicit along a regular grid will be written.
The file is written out in binary, with the first 4 bytes corresponding to the (integer) sampling resolution, R, and the next 4 x R^D bytes corresponding to the (single precision) floating point values of the implicit function. (Here, D is the dimension.)
[--primalGrid]: Enabling this flag when outputing a grid file samples the implicit function at the corners of the grid, rather than the centers of the cells.
[--mesh <output triangle mesh>]: This string is the name of the file to which the triangle mesh will be written. The file is written in PLY format.
This is only supported for dimension 3.
[--iso <iso-value for mesh extraction>]: This floating point value specifies the iso-value at which the implicit surface is to be extracted.
The default value is 0.
[--nonLinearFit]: Enabling this flag has the reconstructor use quadratic interpolation to estimate the positions of iso-vertices.
[--polygonMesh]: Enabling this flag tells the reconstructor to output a polygon mesh (rather than triangulating the results of Marching Cubes).
[--flip]: Enabling this flag flips the orientations of the output triangles.
[--threads <number of processing threads>]: This integer specifies the number of threads across which the algorithm should be parallelized.
The default value for this parameter is equal to the numer of (virtual) processors on the executing machine.
[--verbose]: Enabling this flag provides a more verbose description of the running times and memory usages of individual components of the visualizer.

--in <input geometry file count, geometry file #1, geometry file #2, ...>: These white-space separated strings give the number of geometry files (containing representing either a point cloud in 3D or a mesh) and the names of the individual files.
[--out <output ply file name/header>]: This string is the name of the file/header to which the chunks should be written. If the width of the chunk is W, the file containing the geometry inside the cube [W·i,W·(i+1)]×[W·j,W·(j+1)]×[W·k,W·(k+1)] will be named <output header>.i.j.k.ply.
[--width <chunk width>]: This floating point value specifies the width of the cubes used for chunking.
The default value for this parameter is -1, indicating that the input should be written to a single ouput. (In this case the value of the --out parameter is the name of the single file to which the output is written.
[--radius <padding radius>]: This floating point value specifies the size of the padding region used, as a fraction of the total width of the cube.
The default value for this parameter is 0, indicating that no padding should be used.
[--noNormals]: Enabling this flag lets the chunking code know that, in the case that the input is a point cloud in raw ASCII/binary format, the points do not have normals associated with them..
[--colors]: Enabling this flag lets the chunking code know that, in the case that the input is a point cloud in raw ASCII/binary format, the points have color associatd with them.
[--values]: Enabling this flag lets the chunking code know that, in the case that the input is a point cloud in raw ASCII/binary format, the points have scalar values associated with them.
[--verbose]: Enabling this flag provides a more verbose description of the running times and memory usages of individual components of the visualizer.

HEADER-ONLY LIBRARY

Reconstruction.example.cpp

In addition to executables, the reconstruction code can be interfaced into through the functionality implemented in Reconstructors.h. Using the functionality requires requires choosing a finite element type, FEMSig and defining one input stream and two output streams.

The template parameter FEMSig describes the finite element type, which is a composite of the degree of the finite element and the boundary conditions it satisfies. Given an integer valued Degree and boundary type BType (one of BOUNDARY_FREE, BOUNDARY_DIRICHLET, and BOUNDARY_NEUMANN defined in BSplineData.h), the signature is defined by setting:
```
static const unsigned int FEMSig = FEMDegreeAndBType< Degree , BoundaryType >::Signature;
```

The three streams are defined by overriding virtual stream classes. In the descriptions below, the template parameter Real is the floating point type used to represent data (typically float) and Dim is the integer dimension of the space (fixed at Dim=3). The namespace Reconstructor is omitted for brevity.

Input sample stream: This class derives from the InputSampleStream< Real , Dim > class. The base class has two pure virtual methods that need to be over-ridden:
- void reset( void ):
  This method resets the stream to the start (necessary because the reconstruction code performs two passes over the input samples).
- bool base_read( Point< Real , Dim > &p , Point< Real , Dim > &n ):
  This method tries to read the next pair of positions/normals from the stream, returning true if the read was successful and false if the read failed (i.e. the end of the stream was reached). The class Point< Real , Dim > represents a point in Dim-dimensional space, can be accessed like an array (i.e. overloads the bracked operator) and supports algebraic manipulation like addition and scalar multiplication.
Output vertex stream: This class derives from the OutputVertexStream< Real , Dim > class. The base class has one pure virtual method that needs to be over-ridden:
- void base_write( Point< Real , Dim > p , Point< Real , Dim > g , Real w ):
  This method writes the information for the next vertx into the stream. The data includes the position of the vertex, p, as well as the gradient, g, and density weight, w if the extraction code is asked to compute those.
Output polygon stream: This class derives from the OutputPolygonStream class. The base class has one pure virtual method that needs to be over-ridden:
- void base_write( const std::vector< node_index_type > &polygon ):
  This method writes the information for the next polygon into the stream, with the polygon represented as a std::vector of integral indices. (The type node_index_type is an unsigned int if the BIG_DATA macro is not defined an unsigned long long if it is.)

The reconstructed surface is then computed in two steps:

Poisson::Implicit< Real , Dim , FEMSig >::Implicit( InputSampleStream< Real , Dim > &sStream , SolutionParameters< Real > sParams ):
This constructor creates a Poisson reconstruction object from an input sample stream (sStream) and a description of the reconstruction parameters (sParams) desribing the depth, number of samples per node, etc. (Reconstructors.h, line 229). This object derives from Implicit< Real , Dim , FEMSig >.
void Implicit< Real , Dim , FEMSig >::extractLevelSet( OutputVertexStream< Real , Dim > &vStream , &pStream , LevelSetExtractionParameters meParams ):
This member function takes references to the output vertex and polygon streams (vStream and pStream) and parameters for level-set extraction (meParams) and computes the extracted triangle/polygon mesh, writing its vertices and faces into the corresponding output streams as they are generated (Reconstructors.h, line 98).

Code walk-through:

Reconstruction.example.cpp

An input sample stream generating a specified number of random points on the surface of the sphere is defined in lines 78-115 and constructed in line 307.
An output vertex stream that pushes just the position information to an std::vector of Reals is desfined in lines 182-192 and constructed in line 318.
An output polygon stream that pushes the polygon to an std::vector of std::vector< int >s is defined in lines 164-179 and constructed in line 317.
The reconstructor is constructed in line 310.
The level-set extraction is performed on line 321.

Smoothed Signed Distance

RGBColor

USAGE EXAMPLES (WITH SAMPLE DATA)

PoissonRecon / SSDRecon / SurfaceTrimmer / ChunkPly

For testing purposes, four point sets are provided:

Horse: A set of 100,000 oriented point samples (represented in ASCII format) was obtained by sampling a virtual horse model with a sampling density proportional to curvature, giving a set of non-uniformly distributed points.
The surface of the model can be reconstructed by calling the either Poisson surface reconstructor:
% PoissonRecon --in horse.npts --out horse.ply --depth 10
or the SSD surface reconstructor
% SSDRecon --in horse.npts --out horse.ply --depth 10
Bunny: A set of 362,271 oriented point samples (represented in PLY format) was obtained by merging the data from the original Stanford Bunny range scans. The orientation of the sample points was estimated using the connectivity information within individual range scans.
The original (unscreened) Poisson reconstruction can be obtained by setting the point interpolation weight to zero:
% PoissonRecon --in bunny.points.ply --out bunny.ply --depth 10 --pointWeight 0
By default, the Poisson surface reconstructor uses degree-2 B-splines. A more efficient reconstruction can be obtained using degree-1 B-splines:
% PoissonRecon --in bunny.points.ply --out bunny.ply --depth 10 --pointWeight 0 --degree 1
(The SSD reconstructor requires B-splines of degree at least 2 since second derivatives are required to formulate the bi-Laplacian energy.)
Eagle: A set of 796,825 oriented point samples with color (represented in PLY format) was obtained in the EPFL Scanning 3D Statues from Photos course.
A reconstruction of the eagle can be obtained by calling:
% PoissonRecon --in eagle.points.ply --out eagle.pr.ply --depth 10
(with the RGBA color properties automatically detected from the .ply header).
A reconstruction of the eagle that does not close up the holes can be obtained by first calling:
% SSDRecon --in eagle.points.ply --out eagle.ssd.ply --depth 10 --density
using the --density flag to indicate that density estimates should be output with the vertices of the mesh, and then calling:
% SurfaceTrimmer --in eagle.ssd.ply --out eagle.ssd.trimmed.ply --trim 7
to remove all subsets of the surface where the sampling density corresponds to a depth smaller than 7.
This reconstruction can be chunked into cubes of size 4×4×4 by calling:
% ChunkPly --in 1 eagle.ssd.trimmed.ply --out eagle.ssd.trimmed.chnks --width 4
which partitions the reconstruction into 11 pieces.
Torso: A set of 3,488,432 (torso.points.ply) and an envelope (torso.envelope.ply).
A reconstruction of the torso that constrains the reconstruction to be contained within the envelope can be obtained by calling:
% PoissonRecon --in torso.points.ply --envelope torso.envelope.ply --out torso.pr.ply --depth 10
using the --envelope flag to specify the water-tight mesh constraining the reconstruction.

PoissonReconServer / PoissonReconClient

For testing purposes, two point sets are provided:

Eagle: A set of 796,825 oriented point samples with color was obtained in the EPFL Scanning 3D Statues from Photos course.
Assuming the point-set is placed in the networked file <in dir> and that a networked temporary folder <temp dir> exists, a distributed reconstruction of the eagle over 4 clients at depth 10, outputting the reconstruction to eagle.ply (relative to the directory from the server is run), can be obtained by calling:
% PoissonReconServer --count 4 --depth 10 --in <in dir>/eagle.points.ply --tempDir <temp dir>/temp --out eagle.ply
(with the RGBA color properties automatically detected from the .ply header).
This will initiate the server which will output the address and port for the clients to connect to:
Server Address: <IPv4 address>:<port>
The four clients can then be executed by connecting them to the server:
% PoissonReconClient --port <port> --address <IPv4 address>

% PoissonReconClient --port <port> --address <IPv4 address>

% PoissonReconClient --port <port> --address <IPv4 address>

% PoissonReconClient --port <port> --address <IPv4 address>
Alternatively, the four clients can be executed serially:
% PoissonReconClient --port <port> --address <IPv4 address> --multi 4
Safra Square: For testing purposes, the Safra-Square point set, containing 2,364,268,059 oriented point samples with color, has been generously provided by Resonai.

PointInterpolant / AdaptiveTreeVisualization

For testing purposes, a pair of point-sets is provided:

fitting samples: A set of 1000 random 2D samples from within the square [-1,1,]x[-1,1] along with the evaluation of the quadratic f(x,y)=x*x+y*y at each sample point (represented in ASCII format).
evaluation samples: A set of 4 2D positions at which the fit function is to be evaluated (represented in ASCII format).

The function fitting the input samples can be by calling the point interpolant:

% PointInterpolant --inValues quadratic.2D.fitting.samples --tree quadratic.2D.tree --dim 2

Then, the reconstructed function can be evaluated at the evaluation samples by calling the adaptive tree visualization:

% AdaptiveTreeVisualization --in quadratic.2D.tree --samples quadratic.2D.evaluation.samples

This will output the evaluation positions and values:

0 0 1.33836e-05

0.5 0 0.25001

0.5 0.5 0.500006

2 2 nan

Note that because the (last) evaluation position (2,2) is outside the bounding box of the fitting samples, the function cannot be evaluated at this point and a value of "nan" is output.

ImageStitching

For testing purposes, two panoramas are provided: Jaffa (23794 x 9492 pixels) and OldRag (87722 x 12501 pixels). A seamless panorama can be obtained by running:

% ImageSitching --in pixels.png labels.png --out out.png

EDTInHeat / AdaptiveTreeVisualization

The Euclidean Distance Tranform of the reconstructed horse can be obtained by running:

% EDTInHeat --in horse.ply --out horse.edt --depth 9

Then, the visualization code can be used to extract iso-surfaces from the implicit function.
To obtain a visualization near the input surface, use an iso-value close to zero:

% AdaptiveTreeVisualization.exe --in horse.edt --mesh horse_0.01_.ply --iso 0.01 --flip

(By default, the surface is aligned so that the outward facing normal aligns with the negative gradient. Hence, specifying the --flip flag is used to re-orient the surface.)
To obtain a visualization closer to the boundary of the bounding box, use an iso-value close to zero:

% AdaptiveTreeVisualization.exe --in horse.edt --mesh horse_0.25_.ply --iso 0.25 --flip

(Since the default --scale is 2, a value of 0.25 should still give a surface that is contained within the bounding box.)
To obtain a sampling of the implicit function over a regular grid:

% AdaptiveTreeVisualization.exe --in horse.edt --grid horse.grid

HISTORY OF CHANGES

Version 3:

The implementation of the --samplesPerNode parameter has been modified so that a value of "1" more closely corresponds to a distribution with one sample per leaf node.
The code has been modified to support compilation under MSVC 2010 and the associated solution and project files are now provided. (Due to a bug in the Visual Studios compiler, this required modifying the implementation of some of the bit-shifting operators.)

Version 4:

The code supports screened reconstruction, with interpolation weight specified through the --pointWeight parameter.
The code has been implemented to support parallel processing, with the number of threads used for parallelization specified by the --threads parameter.
The input point set can now also be in PLY format, and the file-type is determined by the extension, so that the --binary flag is now obsolete.
At depths coarser than the one specified by the value --minDepth the octree is no longer adaptive but rather complete, simplifying the prolongation operator.

Version 4.5:

The algorithmic complexity of the solver was reduced from log-linear to linear.

Version 4.51:

Smart pointers were added to ensure that memory accesses were in bounds.

Version 5:

The --density flag was added to the reconstructor to output the estimated depth of the iso-vertices.
The SurfaceTrimmer executable was added to support trimming off the subset of the reconstructed surface that are far away from the input samples, thereby allowing for the generation of non-water-tight surface.

Version 5.1:

Minor bug-fix to address incorrect neighborhood estimation in the octree finalization.

Version 5.5a:

Modified to support depths greater than 14. (Should work up to 18 or 19 now.)
Improved speed and memory performance by removing the construction of integral and value tables.
Fixed a bug in Version 5.5 that used memory and took more time without doing anything useful.

Version 5.6:

Added the --normalWeight flag to support setting a point's interpolation weight in proportion to the magnitude of its normal.

Version 5.7:

Modified the setting of the constraints, replacing the map/reduce implementation with OpenMP atomics to reduce memory usage.
Fixed bugs that caused numerical overflow when processing large point clouds on multi-core machines.
Improved efficiency of the iso-surface extraction phse.

Version 5.71:

Added the function GetSolutionValue to support the evaluation of the implicit function at a specific point.

Version 6:

Modified the solver to use Gauss-Seidel relaxation instead of conjugate-gradients at finer resolution.
Re-ordered the implementation of the solver so that only a windowed subset of the matrix is in memory at any time, thereby reducing the memory usage during the solver phase.
Separated the storage of the data associated with the octree nodes from the topology.

Version 6.1:

Re-ordered the implementation of the iso-surface extraction so that only a windowed subset of the octree is in memory at any time, thereby reducing the memory usage during the extracted phase.

Version 6.11:

Fixed a bug that created a crash in the evaluation phase when --pointWeight is set zero.

Version 6.12:

Removed the OpenMP firstprivate directive as it seemed to cause trouble under Linux compilations.

Version 6.13:

Added a MemoryPointStream class in PointStream.inl to support in-memory point clouds.
Modified the signature of Octree::SetTree in MultiGridOctreeData.h to take in a pointer to an object of type PointStream rather than a file-name.

Version 6.13a:

Modified the signature of Octree::SetIsoSurface to rerun a void. [cloudcompare]
Added a definition of SetIsoVertexValue supporting double precision vertices. [cloudcompare]
Removed Time.[h/cpp] from the repository. [cloudcompare/asmaloney]
Fixed assignment bug in Octree::SetSliceIsoVertices. [asmaloney]
Fixed initialization bug in SortedTreeNodes::SliceTableData and SortedTreeNodes::XSliceTableData. [asmaloney]
Included stdlib.h in Geometry.h. [asmaloney]
Fixed default value bug in declaration of Octree::SetTree. [asmaloney]

Version 7.0:

Added functionality to support color extrapolation if present in the input.
Modified a bug with the way in which sample contributions were scaled.

Version 8.0:

Added support for different degree B-splines. (Note that as the B-spline degree is a template parameter, only degree 1 through 4 are supported. If higher order degrees are desired, additional template parameters can be easily added in the body of the Execute function inside of PoissonRecon.cpp. Similarly, to reduce compilation times, support for specific degrees can be removed.)
Added the --primalGrid flag to support to extraction of a grid using primal sampling.
Changed the implementation of the grid sampling so that computation is now linear, rather than log-linear, in the number of samples.

Version 9.0:

Added support for free boundary conditions.
Extended the solver to support more general linear systems. This makes it possible to use the same framework to implement the Smoothed Signed Distance Reconstruction of Calakli and Taubin (2011).
Modified the implementation of density estimation and input representation. This tends to define a slightly larger system. On its own, this results in slightly increased running-time/footprint for full-res reconstructions, but provides a substantially faster implementation when the output complexity is smaller than the input.

Version 9.01:

Reverted the density estimation to behave as in Version 8.0.

Version 9.011:

Added a parameter for specifying the temporary directory.

Version 10.00:

The code has been reworked to support arbitrary dimensions, finite elements of arbitrary degree, generally SPD systems in the evaluated/integrated values and derivatives of the functions, etc.
For the reconstruction code, added the --width flag which allows the system to compute the depth of the octree given a target depth for the finest resolution nodes.
For the reconstruction code, fixed a bug in the handling of the confidence encoded in the lengths of the normals. In addition, added the flags --confidence and --confidenceBias which allow the user more control of how confidence is used to affect the contribution of a sample.

Version 10.01:

Modified the reconstruction code to facilitate interpolation of other input-sample quantities, in addition to color.

Version 10.02:

Set the default value for --degree in PoissonRecon to 1 and change the definitiion of DATA_DEGREE to 0 for sharper color interpolation.

Version 10.03:

Cleaned up memory leaks and fixed a bug causing ImageStitching and EDTInHeat to SEGFAULT on Linux.

Version 10.04:

Replaced the ply I/O code with an object-oriented implementation.
Updated the code to support compilation under gcc version 4.8.

Version 10.05:

Added cleaner support for warning and error handling.
Minor bug fixes.
Added a --inCore flag that enables keeping the pointset in memory instead of streaming it in from disk.

Version 10.06:

Improved performance.
Modified PoissonRecon and SSDRecon to support processing of 2D point sets.
Modified the 2D implementations of PoissonRecon, SSDRecon, and AdaptiveTreeVisualization to support ouput to .jpg and .png image files.

Version 10.07:

Removed a bug that would cause memory access errors when some slices were empty.

Version 11.00:

Added support for processing point-sets so large that 32-bit indices for octrees are not sufficient. (Enabled by defining the preprocessor variable BIG_DATA in the file PreProcessor.h.
Added C++11 parallelism for compilers that do not support OpenMP.
Added the code for ChunkPly which breaks up large meshes and/or point-sets into chunks.

Version 11.01:

Fixed bug with _mktemp that caused the code to crash on Windows machine with more than 26 cores.

Version 11.02:

Added error handling for numerical imprecision issues arrising when too many samples fall into a leaf node.

Version 12.00:

Added functionality enabling AdaptiveTreeVisualization to output the values of a function at prescribed sample positions.
Added the implementation of PointInterpolant that fits a function to a discrete set of sample values.

Version 13.00:

Enabled passing in a constraint envelope to PoissonRecon, allowing one to define a region that is known to be outside the surface.
Updated ChunkPLY to support processing of input points in either ASCII or binary format.

Version 13.50:

Enabled support for automatically detecting attirbutes of input point cloud (in addition to positions and normals) when provided in .ply format.

Version 13.60:

Modified the implementation of PointInterpolant to support separately prescribing value and gradient constraints.

Version 13.61:

Bug fix addressing the problem that the memory for a DynamicFactory object is dynamically allocated and not only known at construction time.

Version 13.70:

Using the updated PLY libraray with the less restrictive BSD license.

Version 13.71:

Fixed a bug that resulted in incorrect point weighting when the samples were too sparse.

Version 13.72:

Fixed a bug that could result in the reconstruction not solving up to the finest depth when the --width argument is used.

Version 13.73:

Re-fixed a bug that could result in the reconstruction not solving up to the finest depth when the --width argument is used.

Version 13.74:

Fixed a bug that could result in reconstruction failure when the reconstruction depth (e.g. computed using the --width argument) was lower than the full depth value.

Version 13.80:

Updated the SurfaceTrimmer code to better handle small islands.

Version 13.99:

Modified the --width parameter so that it serves as an upper bound on the width of a cell at the finest resolution.
Modified the code so that the output mesh no longer has statistics about processing time/memory.

Version 14.00:

Added support for distributed screened Poisson Surface Reconstruction.

Version 14.01:

Added support for fixed width integer types.

Version 14.02:

Fixed overflow bug when there are more than 2^32 nodes in the tree.

Version 15.00:

Added support for header-only interface.
Added example using the header-only interface for reconstructing surfaces from points randomly sampled from a sphere.

Version 15.01:

Cleaned up interface into the reconstruction library.

SUPPORT

This work was genersouly supported by the National Science Foundation (NSF) grant numbers 0746039 and 1422325.
We are extremely grateful to the EPFL Scanning 3D Statues from Photos course, the Stanford 3D Scanning Repository, and Resonai for sharing their data.
This work was carried out at the Advanced Research Computing at Hopkins (ARCH) core facility, which is supported by the National Science Foundation (NSF) grant number 1920103.