README.md

Shape Gradient Domain (Version 5.0)

links description executable notes examples changes

---

LINKS
[Chuang et al. 2009], [Prada et al. 2016], [Chuang et al. 2016]
Windows (x64) Executables
Source Code
GitHub Repository
(Older Versions: V4.5, V4.0, V3.0, V2.0, V1.0)

---

DESCRIPTION

• This code performs gradient domain processing [Chuang et al. 2009, Chuang et al. 2016] on signals defined on a mesh, where the signal can be either a color-field represented as a color per vertex or is the position of the vertices themselves. The code supports both sharpening and smoothing of the signals through the solution of a screened-Poisson equation. Specifically, given an input signal F, it solves for the signal G minimizing:
  E(G) = ||F-G||² + β⋅||λ⋅∇F - ∇G||²
  where β is the gradient-fitting weight and λ is the gradient scale factor.
• The code supports inhomogenous processing by allowing the user to replace the Riemannian metric, g, given by the embedding, with a metric that adjusts to the curvature of the surface. Specifically, given orthonormal principal curvature directions, the (idenity) metric is replaced with:
  g ← Id. + ε⋅Κ² where Id. is the identity matrix, Κ² is the diagonal matrix whose entries are the sum of the squares of the principal curature values, and ε is the curvature weight. (When ε=0, this reproduces the Riemannian metric given by the embedding.)
  Curvatures are estimated using the surface normals. If none are provided, the vertex normals are estimated as the area-weighted sum of adjacent triangle normals.
• For robustness, the implementation supports pre-smoothing the normals before estimating curvatures. Similar to above, this amounts to minimizing an energy of the form:
  E(G) = ||F-G||² + γ⋅||∇G||²
  where γ is the normal smoothing weight.
  
• In the case that the signal processed describes the vertices' normals, we also support fitting the original geometry to the processed normals using the approach of [Yu et al. 2004].
  Given input positions F and a target normal field N This amounts to minimizing:
  E(G) = ||F-G||² + δ⋅||(∇F - N⋅⟨∇F,N⟩) - ∇G||²
  where δ is the projected gradient fitting weight weight.
  

---

EXECUTABLE

ShapeGradientDomain: Processes either the vertex positions, or per-vertex colors, performing homogeneous/inhomogeneous gradient-domain smoothing and sharpening (with the option of smoothing normals in a pre-processing step)

--in <input geometry>

This string specifies the name of the input geometry, represented in PLY format.

[--out <ouput geometry>]

This string specifies the name of the output geometry, represented in PLY format.

[--nWeight <normal smoothing time>]

This floating point value gives the normal smoothing weight (γ).
The default value for this parameter is 10^-4.


[--gWeight <gradient interpolation weight>]

This floating point value gives the weight for gradient interpolation (β).
The default value for this parameter is 10^-4.


[--gScale <gradient scale>]

This floating point value gives the scale factor for the target gradient field (λ).
The default value for this parameter is 1.0.


[--kWeight <curvature weight>]

This floating point value gives the curvature weight for adjusting the metric (ε).
The default value for this parameter is 0.0.


[--npWeight <normal projection weight>]

This floating point value gives the normal projection weight (δ).
The default value for this parameter is 10².


[--signal]

This inter value describes which signal is to be processed:

• 0: Vertex positions
• 1: Vertex normals (will be assigned if none are give)
• 2: Vertex colors
• 3: Vertex normals used to fit the geometry.

The default value for this parameter is 0.

[--verbose]

If this flag is enabled, the code will output processing information.

ShapeCurvature: Visualizes the estimated total curvature as a gray-scale per-vertex color.

--in <input geometry>

This string specifies the name of the input geometry, represented in PLY format.

[--out <ouput geometry>]

This string specifies the name of the output geometry, represented in PLY format.

[--nWeight <normal smoothing weight>]

This floating point value gives the normal smoothing weight (γ).
The default value for this parameter is 10^-4.


[--verbose]

If this flag is enabled, the code will output processing information.

---

NOTES

• The code requires Eigen as a numerical solver.
  If you are using Eigen and your implementation is backed by Intel's Math Kernel Library (see discussion here), enable the EIGEN_USE_MKL_ALL macro by defining it in the file PreProcessor.h. (The two versions of the Windows executables are compiled with and without MKL support.)
• For consistency of parameters, surfaces are rescaled to have unit area prior to processing (and then scaled back after processing).

---

EXAMPLES

• ShapeGradientDomain:

  The figure below shows example of both homogenous and inhomogeneous geometry processing.
  

  • Top row: Homogeneous sharpening:

         ShapeGradientDomain --in armadillo.ply --out armadillo.sharp.ply --gScale 2 --gWeight <gradient weight> 

  • Middle row: Homogeneous smoothing:

         ShapeGradientDomain --in armadillo.ply --out armadillo.smooth.ply --gScale 0 --gWeight <gradient weight> 

  • Bottom row: Inhomogeneous smoothing:

         ShapeGradientDomain --in armadillo.ply --out armadillo.smooth.ply --gScale 0 --gWeight <gradient weight> --kWeight 0.02

  For all three, the value of <gradient weight> is chosen from {1e-3, 1e-4, 1e-5}
• ShapeCurvature:

  The figure below visualizes the total curvature (square root of the sum of the squares of the principal curvatures) as per-vertex grayscale colors and gives the standard deviations of the estimated total curvature σ_|κ|

       ShapeCurvature --in armadillo.ply --out armadillo.curvature.ply --nWeight <normal smoothing weight>

  The value of <normal smoothing weight> is chosen from {1e-4,1e-5,1e-6}.
  

---

HISTORY OF CHANGES

Version 2.0:

1. Added options to weight both value and gradient interpolation terms.
2. Changed default values to correspond to diffusion time.

Version 3.0:

1. Integrated normal smoothing within the gradient-domain processing application.

Version 4.0:

1. Fixed default value weight to 1.0.
2. Added support for fitting the geometry to prescribed normals.

Version 4.5:

1. Enabled symbolic matrix factorization in pre-processing.
2. Added support (and made default) normal smoothing through per-channel diffusion.

Version 5.0:

1. Removed harmonic normal smoothing
2. Removed normal smoothing iterations
3. Added cuvature visualization executable

Shape Gradient Domain (Version 5.0)

links description executable notes examples changes

---

LINKS
[Chuang et al. 2009], [Prada et al. 2016], [Chuang et al. 2016]
Windows (x64) Executables
Source Code
GitHub Repository
(Older Versions: V4.5, V4.0, V3.0, V2.0, V1.0)

---

DESCRIPTION

• This code performs gradient domain processing [Chuang et al. 2009, Chuang et al. 2016] on signals defined on a mesh, where the signal can be either a color-field represented as a color per vertex or is the position of the vertices themselves. The code supports both sharpening and smoothing of the signals through the solution of a screened-Poisson equation. Specifically, given an input signal F, it solves for the signal G minimizing:
  E(G) = ||F-G||² + β⋅||λ⋅∇F - ∇G||²
  where β is the gradient-fitting weight and λ is the gradient scale factor.
• The code supports inhomogenous processing by allowing the user to replace the Riemannian metric, g, given by the embedding, with a metric that adjusts to the curvature of the surface. Specifically, given orthonormal principal curvature directions, the (idenity) metric is replaced with:
  g ← Id. + ε⋅Κ² where Id. is the identity matrix, Κ² is the diagonal matrix whose entries are the sum of the squares of the principal curature values, and ε is the curvature weight. (When ε=0, this reproduces the Riemannian metric given by the embedding.)
  Curvatures are estimated using the surface normals. If none are provided, the vertex normals are estimated as the area-weighted sum of adjacent triangle normals.
• For robustness, the implementation supports pre-smoothing the normals before estimating curvatures. Similar to above, this amounts to minimizing an energy of the form:
  E(G) = ||F-G||² + γ⋅||∇G||²
  where γ is the normal smoothing weight.
  
• In the case that the signal processed describes the vertices' normals, we also support fitting the original geometry to the processed normals using the approach of [Yu et al. 2004].
  Given input positions F and a target normal field N This amounts to minimizing:
  E(G) = ||F-G||² + δ⋅||(∇F - N⋅⟨∇F,N⟩) - ∇G||²
  where δ is the projected gradient fitting weight weight.
  

---

EXECUTABLE

ShapeGradientDomain: Processes either the vertex positions, or per-vertex colors, performing homogeneous/inhomogeneous gradient-domain smoothing and sharpening (with the option of smoothing normals in a pre-processing step)

--in <input geometry>

This string specifies the name of the input geometry, represented in PLY format.

[--out <ouput geometry>]

This string specifies the name of the output geometry, represented in PLY format.

[--nWeight <normal smoothing time>]

This floating point value gives the normal smoothing weight (γ).
The default value for this parameter is 10^-4.


[--gWeight <gradient interpolation weight>]

This floating point value gives the weight for gradient interpolation (β).
The default value for this parameter is 10^-4.


[--gScale <gradient scale>]

This floating point value gives the scale factor for the target gradient field (λ).
The default value for this parameter is 1.0.


[--kWeight <curvature weight>]

This floating point value gives the curvature weight for adjusting the metric (ε).
The default value for this parameter is 0.0.


[--npWeight <normal projection weight>]

This floating point value gives the normal projection weight (δ).
The default value for this parameter is 10².


[--signal]

This inter value describes which signal is to be processed:

• 0: Vertex positions
• 1: Vertex normals (will be assigned if none are give)
• 2: Vertex colors
• 3: Vertex normals used to fit the geometry.

The default value for this parameter is 0.

[--verbose]

If this flag is enabled, the code will output processing information.

ShapeCurvature: Visualizes the estimated total curvature as a gray-scale per-vertex color.

--in <input geometry>

This string specifies the name of the input geometry, represented in PLY format.

[--out <ouput geometry>]

This string specifies the name of the output geometry, represented in PLY format.

[--nWeight <normal smoothing weight>]

This floating point value gives the normal smoothing weight (γ).
The default value for this parameter is 10^-4.


[--verbose]

If this flag is enabled, the code will output processing information.

---

NOTES

• The code requires Eigen as a numerical solver.
  If you are using Eigen and your implementation is backed by Intel's Math Kernel Library (see discussion here), enable the EIGEN_USE_MKL_ALL macro by defining it in the file PreProcessor.h. (The two versions of the Windows executables are compiled with and without MKL support.)
• For consistency of parameters, surfaces are rescaled to have unit area prior to processing (and then scaled back after processing).

---

EXAMPLES

• ShapeGradientDomain:

  The figure below shows example of both homogenous and inhomogeneous geometry processing.
  

  • Top row: Homogeneous sharpening:

         ShapeGradientDomain --in armadillo.ply --out armadillo.sharp.ply --gScale 2 --gWeight <gradient weight> 

  • Middle row: Homogeneous smoothing:

         ShapeGradientDomain --in armadillo.ply --out armadillo.smooth.ply --gScale 0 --gWeight <gradient weight> 

  • Bottom row: Inhomogeneous smoothing:

         ShapeGradientDomain --in armadillo.ply --out armadillo.smooth.ply --gScale 0 --gWeight <gradient weight> --kWeight 0.02

  For all three, the value of <gradient weight> is chosen from {1e-3, 1e-4, 1e-5}
• ShapeCurvature:

  The figure below visualizes the total curvature (square root of the sum of the squares of the principal curvatures) as per-vertex grayscale colors and gives the standard deviations of the estimated total curvature σ_|κ|

       ShapeCurvature --in armadillo.ply --out armadillo.curvature.ply --nWeight <normal smoothing weight>

  The value of <normal smoothing weight> is chosen from {1e-4,1e-5,1e-6}.
  

---

HISTORY OF CHANGES

Version 2.0:

1. Added options to weight both value and gradient interpolation terms.
2. Changed default values to correspond to diffusion time.

Version 3.0:

1. Integrated normal smoothing within the gradient-domain processing application.

Version 4.0:

1. Fixed default value weight to 1.0.
2. Added support for fitting the geometry to prescribed normals.

Version 4.5:

1. Enabled symbolic matrix factorization in pre-processing.
2. Added support (and made default) normal smoothing through per-channel diffusion.

Version 5.0:

1. Removed harmonic normal smoothing
2. Removed normal smoothing iterations
3. Added cuvature visualization executable