maxkohlbrenner / ExteriorPoissonRecon

Exterior Poisson Reconstruction

Exterior Poisson Reconstruction (Version 1.00)

links executables usage changes

---

This software supports reconstruction of co-dimension two manifolds.

---

LINKS

Papers: [Kohlbrenner, Lee, Kazhdan, and Alexa, 2023],
Executables: Win64
Source Code: ZIP GitHub
Older Versions:

---

EXECUTABLES

Sample: Generates a sampling of points and frames (encoded as the linearized entries of the upper triangle of a skew-symmetric matrix) from co-dimension two manifolds in 3D and 4D.

--type <input geometry type>

This string specifies the type of geometry the points should be sampled from. Supported types include:

For points sampled from 3D curves:
• line_segment: Points lie on a (straight) line segment
• circle: Points lie on a circle
• link: Points lie on two interlocking circles
• spiral:<r>: Points lie on a spiral with r rotations
• torus_knot:<p>:<q>: Points lie on a (p,q) torus-knot
• borromean_rings: Points lie on interlocking Borromean rings For points sampled from 4D surfaces:
• clifford_torus: Points lie on the Clifford torus
• hopf_torus:<n>:<a>: Points lie on the Hopf torus with n nodes and amplitude a.
  Reasonable values for amplitude are in the range [0.1,0.5].

[--out <output file name>]

This optional string value specifies the name of the file to which the samples will be written.
The file will be written out in PLY format, with x-, y-, z-, and (for surfaces in 4D) w-coordinates of a sample's position encoded by the properties x, y, z, and (for surfaces in 4D) w, and the orientation of the sample given by the coefficients of a skew-symmetric matrix, encoded by the properties skew_<c>_<r> with 0≤c,r<3 for curves in 3D and 0≤c,r<4 for surfaces in 4D.
If this argument is not provided, no output is generated.

[--res <sample resolution>]

This optional integer value specifies the resolution of the sampling.
The default value for this parameter is 1024.

[--aNoise <angular noise>]

This optional floating point value specifies the deviation of noise in the samples' orientations (in units of degrees).
The default value for this parameter is 0.

[--pNoise <positional noise>]

This optional floating point value specifies the deviation of noise in the samples' positions (in normalized units).
The default value for this parameter is 0.

[--sNoise <spot noise>]

This optional floating point value specifies the fraction of the number of input samples that should be added as spot noise.
The default value for this parameter is 0.

[--regular]

If enabled, samples will be obtained by regularly sampling in parameter space.

ExteriorPoissonRecon: Reconstructs an implicit function, sampled over a regular grid with two values per grid cell, from a sampling of points and frames (encoded as the entries of a skew-symmetric matrix).

--in <input points and frames>

This string value specifies the name of the file containing the points and frames.
The file is assumged to be in PLY format, with x-, y-, z-, and (for surfaces in 4D) w-coordinates of a sample's position encoded by the properties x, y, z, and (for surfaces in 4D) w, and the orientation of the sample given by the coefficients of a skew-symmetric matrix, encoded by the properties skew_<c>_<r> with 0≤c,r<3 for curves in 3D and 0≤c,r<4 for surfaces in 4D.


[--out <grid header>]

This optional string value specifies the header for the grid files describing the estimated density distribution and the reconstructed implicit function.
The density will be output to the file <grid header>.density.grid and the reconstructed implicit function will be output to the file <grid header>.grid.
If this argument is not provided, no output is generated.

[--depth <reconstruction depth>]

This optional integer value is the depth of the grid that will be used for reconstruction. Running at depth d corresponds to solving on a grid whose resolution is than 2^d x 2^d x ... .
The default value for this parameter is 5.

[--sWeight <screening weight>]

This optional floating point value is the screening weight used for reconstruction.
The default value for this parameter is 50.

[--dWeight <Dirichlet weight>]

This optional floating point value is the Dirichlet weight used for reconstruction.
The default value for this parameter is 0.003125.

[--scale <scale factor>]

This optional 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.

[--verbose <verbosity>]

This optional integer value specifies the level of verbosity of the executable's output to the command prompt.

• 0: No ooutput
• 1: Global residual error
• 2: Residual error after each level of the multigrid hierarchy

The default value is 0.

Extract: Extracts a co-dimension two manifold as a level set from the reconstructed implicit function grid.

--in <input implicit grid>

This string value is the file-name of the grid sampling the reconstructed implicit function.

[--out <output simplicial mesh>]

This optional string value specifies the file to which the extracted level-set will be written.
The file will be written out in PLY format, with x-, y-, z-, and (for surfaces in 4D) w-coordinates of the positions encoded by the properties x, y, z, and (for surfaces in 4D) w.
If this argument is not provided, no output is generated.

[--density <input density grid>]

This optional string value is the file-name of the grid sampling the density values.
If this argument is not provided, no density-based trimming is performed.

[--trimDensity <trimming density>]

This optional floating point value specifies the density that must be met by some point on a connected component of the reconstruction for the connected component to be kept.
The argument is ignored if the --density argument is not provided.
The default value for this argument is 0.0.

Stereo: Replaces the vertices of a mesh in 4D with their positions in 3D after stereographic projection.

--in <input 4D mesh>

This string value is the file-name of the input (4D) mesh.
The file is assumed to be in PLY format, with x-, y-, z-, and w-coordinates of the positions encoded by the properties x, y, z, and w.

[--out <output 3D mesh>]

This string value is the file-name of the output (3D) mesh.
The file will be written out in PLY format, with x-, y-, and z-coordinates of the positions encoded by the properties x, y, and z.
If this argument is not provided, no output is generated.

[--stereo <x, y, z, and w>]

This optional quadruple of floating point values specifies the 4D axis of stereographic projection.
The default value for this argument is 0, 0, 0, 1.

Dilate: Dilate a curve in 3D into a tube.

--in <input curve>

This string value is the file-name of the input (3D) curve.
The file is assumed to be in PLY format, with x-, y-, and z-coordinates of the positions encoded by the properties x, y, and z. Additionally the frame at each point (defined by the gradients of the implicit function) is encoded by the properties nx1, ny1, nz1, nx1, ny1, and nz2.

[--out <output tube>]

This optional string value specifies the file to which the extracted level-set will be written.
The file will be written out in PLY format, with x-, y-, z-coordinates of the positions encoded by the properties x, y, and z.
If this argument is not provided, no output is generated.

[--radius <tubular radius>]

This optional floating point value specifies the radius of the tube (in units of curve diameter).
The default value for this argument is 1/64.

---

USAGE EXAMPLES

Sample / ExteriorPoissonRecon / Extract / Dilate

To reconstruct a dilated (4,5) torus-knot one proceeds in four steps:

1. Construct the framed samples:

   % Sample --type torus_knot:4:5 --out tk.4.5.samples.ply

2. Reconstruct the implicit function:

   % ExteriorPoissonRecon --in tk.4.5.samples.ply --out tk.4.5

3. Extract the connected components of the curve near regions of high sampling density:

   % Extract --in tk.4.5.grid --density tk.4.5.density.grid --out tk.4.5.curve.ply --trimDensity 2

4. Dilate the curve:

   % Dilate --in tk.4.5.curve.ply --out tk.4.5.curve.dilated.ply

Sample / ExteriorPoissonRecon / Extract / Stereo

To reconstruct a three-lobed Hopf Torus one proceeds in four steps:

1. Construct the framed samples:

   % Sample --type hopf_torus:3:0.5 --out ht.3.samples.ply

2. Reconstruct the implicit function:

   % ExteriorPoissonRecon --in ht.3.samples.ply --out ht.3

3. Extract the surface in 4D:

   % Visualize4D --in ht.3.grid --out ht.3.surface.4D.ply

4. Stereographically project to a surface in 3D

   % Stereo --in ht.3.surface.4D.ply --out ht.3.surface.3D.ply

---

HISTORY OF CHANGES

Version 1.00:

1. Initial release