Dense Point-to-Point Correspondences for Genus-Zero Surfaces (V1.0)

links executables usage notes changes

This distribution contains code for constructing dense point-to-point correspondences between two genus-zero models. Specifically, it provides implementations for:

Computing a Möbius-centered conformal parametrization over the sphere
Evolving the parametrization to make it authalic
Computing Heat Kernel Signatures for a surface
Rotationally aligning two spherical parametrizations and then refining using optical flow
Transforming a pair of spherical parametrizations into a pair of vertex-to-barycentric-coordinates correspondences

LINKS

Papers

[Kazhdan, Solomon, and Ben-Chen, 2012]

[Baden, Crane, and Kazhdan, 2018]

[Lee and Kazhdan, 2019]

Binaries

Windows Executables

Windows libraries and DLLs

Source Code

ZIP

GitHub

License

BSD

EXECUTABLES

--in <input mesh>: This string is the name of the file from which the mesh will be read.
The file is assumed to be in the PLY format.
The file is written in PLY format and will contain vertices with fields "x", "y", "z" (for the original vertex positions), "px", "py", "pz" (for the associated positions on the unit sphere), and "red", "green", "blue" (for the per-vertex colors). If no colors are provided, they will be assigned using the surface normals.
[--out <output spherical parametrization>]: This string is the name of the file to which the spherically parametrized mesh will be written.
The file is written in PLY format and will contain vertices with fields "x", "y", "z" (for the original vertex positions), "px", "py", "pz" (for the associated positions on the unit sphere), and "red", "green", "blue" (for the per-vertex colors).
[--steps <number of CMCF iterations>]: This integer values specifies the number of Conformalized Mean Curvature Flow iterations to be used to obtain the conformal spherical parametrization.
The default value for this parameter is 100.
[--stepSize <the temporal size of each CMCF step>]: This floating point values specifies the units for the temporal discretization of the Conformalized Mean Curvature Flow.
The default value for this parameter is 0.1.
[--cutOff <Möbius centering cut-off>]: This floating point value specifies the threshold for terminating the Möbius centering iterations.
The default value for this parameter is 10^(-10).
[--c2i <center to inversion type>]: This integer value specifies how the gradient descent value is to be interpreted as a center of inversion. A value of 0 indicates that a trivial interpretation is to be used. A value of 1 indicates that a golden section search should be performed along the descent direction. A value of 2 indicates that the length of centering transformation should be rescaled using the metric for the Poincaré disk model.
The default value for this parameter is 2.
[--verbose]: If enabled, details regarding the running times of the different stages of processing are output.

--in <input spherical parametrization>: This string is the name of the file from which the spherically parametrized mesh will be read.
The file is written in PLY format and will contain vertices with fields "x", "y", "z" (for the original vertex positions), "px", "py", "pz" (for the associated positions on the unit sphere), and "red", "green", "blue" (for the per-vertex colors). If the input contains colors, they will be copied to the output. Otherwise, colors are assigned using the surface normals.
[--out <output spherical parametrization>]: This string is the name of the file to which the authalically evolved spherical parametrization mesh will be written.
The file is written in PLY format and will contain vertices with fields "x", "y", "z" (for the original vertex positions), "px", "py", "pz" (for the associated positions on the unit sphere), and "red", "green", "blue" (for the per-vertex colors). If the input contains colors, they will be copied to the output. Otherwise, colors are assigned using the surface normals.
[--res <spherical grid resolution>]: This integer values specifies the resolution of the spherical grid over which the parametrization is discretized.
The default value for this parameter is 256.
[--steps <number of authalic evolution iterations>]: This integer values specifies the number of evolution iterations to be used to make the distribution of mass over the sphere become uniform.
The default value for this parameter is 100.
[--stepSize <temporal size of each authalic evolution step>]: This floating point values specifies the units for the temporal discretization of the authalic evolution.
The default value for this parameter is 0.005.
[--cIters <number of centering iterations to be performed in each step>]: This integer values specifies the number of Möbius centering steps that are to be performed after each step of authalic evolution.
The default value for this parameter is 3.
[--smooth <heat diffusion value>]: This floating point values specifies the amount of smoothing to applied to the log scale factors prior to computing gradients.
The default value for this parameter is 0.0025.
[--useGSS]: If enabled, golden section search should be performed for Möbius centering. Otherwise, the Poincaré disk model is used.
[--verbose]: If enabled, details regarding the running times of the different stages of processing are output.

--in <input mesh>: This string is the name of the file from which the mesh will be read.
The file is assumed to be in the PLY format.
[--out <output Heat Kernel Signatures>]: This string is the name of the file to which the Heat Kernel Signatures will be written.
[--dim <number of Heat Kernel Signatures time scales> <the values of the HKS time scales>]: This collection of integer and floating points specifies the number of Heat Kernel Signatures to be computed and the time scale for each one.
The default value for this parameter size is 6 Heat Kernel Signatures with time scales 1., 0.5, 0.25, 0.125, 0.0725, and 0.01.
[--dim <spectrum dimension>]: This integer value specifies the maximum number of eigenvectors to be used in computing the Heat Kernel Signature.
The default value for this parameter is 200.
[--off <spectral offset>]: This floating point value specifies the shift used in the shift-and-inverse implementation of the generalized eigenvalue problem.
The default value for this parameter is 100.0.
[--lump]: If enabled, the mass matrix used for computing the spectrum is lumped..
[This is only used in the case that the input is in PLY format.]
[--verbose]: If enabled, details regarding the running times of the different stages of processing are output.

--in <source and target spherical parametrizations>: This pair of strings give the names of the files from which the source and target spherically parametrized meshes will be read.
The file is written in PLY format and will contain vertices with fields "x", "y", "z" (for the original vertex positions), "px", "py", "pz" (for the associated positions on the unit sphere), and "red", "green", "blue" (for the per-vertex colors). If the input contains colors, they will be copied to the output. Otherwise, colors are assigned using the surface normals.
[--signal <source and target signals for registration>]: This pair of strings give the names of the files containing the (HKS) signals used for registration.
[--out <output source and target parametrizations>]: This pair of strings give the names of the files to which the registered spherical parametrizationd mesh will be written.
The file is written in PLY format and will contain vertices with fields "x", "y", "z" (for the original vertex positions), "px", "py", "pz" (for the associated positions on the unit sphere), and "red", "green", "blue" (for the per-vertex colors).
[--res <initial spherical grid resolution>]: This integer values specifies the resolution of the coarsest spherical grid used for registration. At each subsequent level of the multi-resolution hierarchy, the resolution is multiplied by a factor of two.
The default value for this parameter is 16.
[--rotRes <spherical grid resolution for rotational alignment>]: This integer values specifies the resolution of the spherical grid used for rotational alignment. At each subsequent level of the multi-resolution hierarchy, the resolution is multiplied by a factor of two.
If this parameter is not specified, the finest resolution of the multiresolution hierarchy is used.
[--sWeight <flow field smoothing weight>]: This floating point value value specifies given to the flow field smoothness term in the optical flow.
The default value for this parameter is 0.05.
[--solvesPerLevel <number of optical flow iterations>]: This integer values specifies the number of optical flow iterations to be performed at each level of the multiresolution hierarchy..
The default value for this parameter is 6.
[--maxRot <maximum number of rotation candidates>]: This integer value specifies the maximum of rotation candidates to consider for alignment.
The default value for this parameter is 4.
[--rSeparation <rotation separation distance>]: This floating point value specifies the minimum Frobenius distance between rotations when computing rotational alignment candidates.
The default value for this parameter is 3.0.
[--cFraction <minimum correlation fraction>]: This floating point value specifies the lower bound on fraction between the correlation value of a candidate rotation and the maximal corelation value.
The default value for this parameter is 0.9.
[--rotate <rotation candidate index>]: This integer value specifies which rotation candidate to use for registration.
If no value is specified and output files are specified, all rotation candidates are considered and the result from the best one are written out. If no value is specified and the viewer is used, no rotation is applied.
[--verbose]: If enabled, details regarding the running times of the different stages of processing are output.

--in <registered source and target spherical parametrizations>: This pair of strings give the names of the files from which the registered source and target spherically parametrized meshes will be read.
The file is written in PLY format and will contain vertices with fields "x", "y", "z" (for the original vertex positions) and "px", "py", "pz" (for the associated positions on the unit sphere).
[--out <output correspondences>]: This pair of strings give the names of the files to which the source-to-target and target-to-source correspondences are written. The source-to-target (resp. target-to-source) correspondence files is written in ASCII with a single line for each source (resp. target) vertex, giving the integer index of the target (resp. source) triangle containing the corresponding point and the three floating point barycentric coordinates.
[--verbose]: If enabled, details regarding the running times of the different stages of processing are output.

USAGE
Given genus-zero source and target mesh files, source.ply and target.ply, correspondences can be computed by running the following steps:

Computing the centered spherical parametrizations:
% CMCFViewer --in source.ply --out source.cmcf.ply % CMCFViewer --in target.ply --out target.cmcf.ply
Performing the authalic evolution:
% AuthalicEvolutionViewer --in source.cmcf.ply --out source.cmcf.ae.ply % AuthalicEvolutionViewer --in target.cmcf.ply --out target.cmcf.ae.ply
Computing the Heat Kernel Signatures to use as registration signals:
% GetHKS --in source.ply --out source.signal % GetHKS --in target.ply --out target.signal
Registering the source and target:
% OpticalFlowViewer --in source.cmcf.ae.ply target.cmcf.ae.ply --signal source.signal target.signal --out source_to_target.ply target_to_source.ply
Computing the correspondences from the registered spherical parametrizations:
% GetCorrespondences --in source_to_target.ply target_to_source.ply --out source_to_target.txt target_to_source.txt

NOTES

The implementation of this code relies on the Eigen, Spectra, SOFT, and FFTW libraries. The source for Eigen, Spectra, and SOFT are included and should compile under both Windows and Linux. For the FFTW, Windows .lib and .dll files can be found here.

CHANGES

SUPPORT
This work genersouly supported by NSF grant #1422325.

HOME