Surface

Compute a 3D triangle mesh from content of the reconstruction volume. More...

Typedefs
typedef int	reme_surface_t
	Handle referencing a surface object.
reme_error_t	reme_surface_create (reme_context_t c, reme_surface_t *s)
	Create a new surface object.
reme_error_t	reme_surface_destroy (reme_context_t c, reme_surface_t *s)
	Destroy a previously created surface object.
reme_error_t	reme_surface_bind_generation_options (reme_context_t c, reme_surface_t s, reme_options_t o)
	Access the surface generation options.
reme_error_t	reme_surface_bind_poisson_options (reme_context_t c, reme_surface_t s, reme_options_t o)
	Access the poisson reconstruction options.
reme_error_t	reme_surface_bind_decimation_options (reme_context_t c, reme_surface_t s, reme_options_t o)
	Access the surface decimation options.
reme_error_t	reme_surface_bind_remesh_options (reme_context_t c, reme_surface_t s, reme_options_t o)
	Access the surface remeshing options.
reme_error_t	reme_surface_generate (reme_context_t c, reme_surface_t s, reme_volume_t v)
	Extract the iso-surface from the given volume.
reme_error_t	reme_surface_poisson (reme_context_t c, reme_surface_t s)
	Perform poisson reconstruction on the extracted surface.
reme_error_t	reme_surface_decimate (reme_context_t c, reme_surface_t s)
	Decimate the extracted surface.
reme_error_t	reme_surface_remesh (reme_context_t c, reme_surface_t s)
	Remesh the extracted surface.
reme_error_t	reme_surface_transform (reme_context_t c, reme_surface_t s, const float *coordinates)
	Transform the surface.
reme_error_t	reme_surface_colorize_vertices (reme_context_t c, reme_surface_t s, reme_volume_t v)
	Colorize surface vertices using the color information stored in the reconstruction volume.
reme_error_t	reme_surface_inpaint_vertices (reme_context_t c, reme_surface_t s)
	Paint missing vertex colors.
reme_error_t	reme_surface_get_points (reme_context_t c, reme_surface_t s, const float **coordinates, int *length)
	Get points of a surface.
reme_error_t	reme_surface_get_normals (reme_context_t c, reme_surface_t s, const float **coordinates, int *length)
	Get point normals of a surface.
reme_error_t	reme_surface_get_vertex_colors (reme_context_t c, reme_surface_t s, const float **coordinates, int *length)
	Get colors of surface vertices.
reme_error_t	reme_surface_get_triangles (reme_context_t c, reme_surface_t s, const unsigned int **indices, int *length)
	Get triangle faces of a surface.
reme_error_t	reme_surface_save_to_file (reme_context_t c, reme_surface_t s, const char *filename)
	Export the surface to file.

Detailed Description

Compute a 3D triangle mesh from content of the reconstruction volume.

This modules provides methods to generate triangle meshes from reconstruction volumes. Besides basic surface extraction, hole closing and decimation functionality is provided.

The example below illustrates the functionality.

  // Create a new empty surface
  reme_surface_t m;
  reme_surface_create(c, &m);

  // We use an options object to control various aspects of the generation process
  reme_options_t o;
  reme_options_create(c, &o);

  // Bind the options that define how the basic surface is extracted from the volume.
  reme_surface_bind_generation_options(c, m, o);

  // We disable merging of close vertices at this stage because the data is directly
  // passed into poisson reconstruction which deals with duplicate vertices anyway
  reme_options_set_bool(c, o, "merge_duplicate_vertices", false);

  // Extract surface from volume.
  reme_surface_generate(c, m, v);

  // Close holes through Poisson reconstruction
  reme_surface_bind_poisson_options(c, m, o);
  reme_options_set_int(c, o, "depth", 8);  
  reme_surface_poisson(c, m);

  // Reduce mesh down to 20k triangles
  reme_surface_bind_decimation_options(c, m, o);
  reme_options_set_int(c, o, "maximum_faces", 20000);  
  reme_surface_decimate(c, m);

  // View the result and wait until the user closes the viewer
  reme_viewer_t viewer;
  reme_viewer_create_surface(c, m, "This is ReconstructMeSDK", &viewer);
  reme_viewer_wait(c, viewer);

  // Export mesh
  reme_surface_save_to_file(c, m, "test.ply");

Typedef Documentation

typedef int reme_surface_t

Handle referencing a surface object.

A reme_surface_t represents a 3D mesh surface extracted from a volume. Its associated methods allow to influence the generation process, access mesh data and save volumes using our exporters.

Function Documentation

reme_error_t reme_surface_create	(	reme_context_t	c,
		reme_surface_t *	s
	)

Create a new surface object.

Parameters

c	A valid context object
s	A pointer that will receive the handle of the created surface

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_colorize.cpp, example_reconstructmesdk_one_minute.cpp, example_reconstructmesdk_options_type_safe.cpp, example_reconstructmesdk_point_and_shoot_with_colors.cpp, example_reconstructmesdk_sensor_multi_independent.cpp, example_reconstructmesdk_sensor_printing.cpp, and example_reconstructmesdk_surface.cpp.

reme_error_t reme_surface_destroy	(	reme_context_t	c,
		reme_surface_t *	s
	)

Destroy a previously created surface object.

Parameters

c	A pointer to a valid context object
s	A mutable pointer to a valid surface handle to destroy

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_colorize.cpp, example_reconstructmesdk_one_minute.cpp, example_reconstructmesdk_point_and_shoot_with_colors.cpp, and example_reconstructmesdk_sensor_printing.cpp.

reme_error_t reme_surface_bind_generation_options	(	reme_context_t	c,
		reme_surface_t	s,
		reme_options_t	o
	)

Access the surface generation options.

Associated Protocol Buffers Specification

// Surface generation from reconstruction volume
message generation_options {
  // When enabled duplicate vertices within a certain radius are merged towards a single vertex.
  optional bool merge_duplicate_vertices = 1 [default = true];
  // Defines merge radius. Larger values will perform a simple decimation
  optional float merge_radius = 2 [default = 0.00001];
}

Parameters

c	A valid context object
s	A valid surface object
o	A valid options binding object

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_surface.cpp.

reme_error_t reme_surface_bind_poisson_options	(	reme_context_t	c,
		reme_surface_t	s,
		reme_options_t	o
	)

Access the poisson reconstruction options.

Associated Protocol Buffers Specification

// Poisson surface generation options
message poisson_options {
  optional int32 depth = 1 [default = 8];
  optional int32 solver_divide = 2 [default = 8];
  optional int32 iso_divide = 3 [default = 8];
  optional int32 minimum_samples_per_node = 4 [default = 1];
  optional float scale = 5 [default = 1.25];  
  optional bool enable_manifold = 6 [default = true];  
  optional int32 minimum_depth = 7 [default = 5];
}

Parameters

c	A valid context object
s	A valid surface object
o	A valid options binding object

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_options_type_safe.cpp, and example_reconstructmesdk_surface.cpp.

reme_error_t reme_surface_bind_decimation_options	(	reme_context_t	c,
		reme_surface_t	s,
		reme_options_t	o
	)

Access the surface decimation options.

Associated Protocol Buffers Specification

// Mesh decimation options
message decimation_options {

  // Decimate to target complexity.
  // Range: 0..inf
  optional int32 maximum_faces = 1 [default = 100000];  

  // Maximum quadric error to accept per collapse. The quadric error is similar 
  // to the Hausdorff Distance.
  // Range: 0..inf
  optional float maximum_quadric_error = 2 [default = 100000];

  // Minimum triangle roundness. Normalized triangle roundness with respect to 
  // equiliteral triangle shape.
  // Range: 0..1
  optional float minimum_triangle_roundness = 3 [default = 0];

  // Maximum normal angle error in degrees.
  // Range: 0..180
  optional float maximum_angle_error = 4 [default = 90];

  // Preserve the boundary of the mesh.
  optional bool preserve_boundary = 5 [default = false];

  // Preserve the boundary of the mesh.
  optional float maximum_color_error = 6 [default = 765];
}

Parameters

c	A valid context object
s	A valid surface object
o	A valid options binding object

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_surface.cpp.

reme_error_t reme_surface_bind_remesh_options	(	reme_context_t	c,
		reme_surface_t	s,
		reme_options_t	o
	)

Access the surface remeshing options.

Associated Protocol Buffers Specification

// Mesh remeshing options
message remeshing_options {

  // Minimum target edge length in remeshing. 
  // Range: 0..inf and -1.
  // Leave at -1 to auto-calculate from average mesh edge length
  optional float minimum_edge_length = 1 [default = -1];

  // Maximum target edge length in remeshing. 
  // Range: 0..inf and -1.
  // Leave at -1 to auto-calculate from average mesh edge length
  optional float maximum_edge_length = 2 [default = -1];

  // Maximum color error to tolerate in remeshing.
  // If the error in color change when collapsing an edge is above
  // this threshold, the collapse is not tolerated. Note that this property
  // is only taken into account if the input mesh has vertex colors.
  // Range 0..255*3
  optional float maximum_color_error = 3 [default = 20.0];

  // Maximum curfvate error to tolerate in remeshing.
  // If the error in geometric change when collapsing an edge is above
  // this threshold, the collapse is not tolerated.
  // Range 0..1
  optional float maximum_curvate_error = 4 [default = 0.5];

  // Instead of adaptive remeshing perform a uniform remeshing.
  // Use the maximum_edge_length property to control the target resolution.
  // Note that maximum_color_error and maximum_curvate_error would be respected
  // in this mode.
  optional bool uniform = 5 [default = false];

  // Number of iterations to apply.
  optional int32 iterations = 6 [default = 5];
}

Parameters

c	A valid context object
s	A valid surface object
o	A valid options binding object

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_colorize.cpp.

reme_error_t reme_surface_generate	(	reme_context_t	c,
		reme_surface_t	s,
		reme_volume_t	v
	)

Extract the iso-surface from the given volume.

The surface is generated with respect to the world coordinate system.

In case you are using an unlicensed version of ReconstructMe SDK, this function blocks for at least 15 seconds. Without this limitation the mesh is usually generated in under a second.

Parameters

c	A valid context object
s	A valid surface object
v	A valid volume object

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_colorize.cpp, example_reconstructmesdk_one_minute.cpp, example_reconstructmesdk_point_and_shoot_with_colors.cpp, example_reconstructmesdk_sensor_multi_independent.cpp, example_reconstructmesdk_sensor_printing.cpp, and example_reconstructmesdk_surface.cpp.

reme_error_t reme_surface_poisson	(	reme_context_t	c,
		reme_surface_t	s
	)

Perform poisson reconstruction on the extracted surface.

Use reme_surface_bind_poisson_options to control the decimation process.

Parameters

c	A valid context object
s	A valid surface object

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_point_and_shoot_with_colors.cpp, and example_reconstructmesdk_surface.cpp.

reme_error_t reme_surface_decimate	(	reme_context_t	c,
		reme_surface_t	s
	)

Decimate the extracted surface.

Use reme_surface_bind_decimation_options to control the decimation process. If the input mesh has vertex colors those will be respected in the remesh process.

Note that after the decimation vertex colors will be incorrect. You should generate them again using reme_surface_colorize_vertices and reme_surface_inpaint_vertices.

In contrast to reme_surface_remesh this function only reduces the number of faces and does not generate an isotropic surface.

Parameters

c	A valid context object
s	A valid surface object

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_surface.cpp.

reme_error_t reme_surface_remesh	(	reme_context_t	c,
		reme_surface_t	s
	)

Remesh the extracted surface.

Attempts to create an isotropic surface. Isotropic remeshing of surfaces tries to resample the surface to obtain a triangle tesselation, where the shape of each triangle is not biased in a particular direction (isotropy).

Use reme_surface_bind_remesh_options to control the remeshing process. If the input mesh has vertex colors those will be respected in the remesh process.

Note that after the remesh vertex colors will be incorrect. You should generate them again using reme_surface_colorize_vertices and reme_surface_inpaint_vertices.

Parameters

c	A valid context object
s	A valid surface object

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_colorize.cpp.

reme_error_t reme_surface_transform	(	reme_context_t	c,
		reme_surface_t	s,
		const float *	coordinates
	)

Transform the surface.

This will transform the points and normals of the surface.

Parameters

c	A valid context object
s	A valid surface object
coordinates	A pointer to constant Transform data.

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

reme_error_t reme_surface_colorize_vertices	(	reme_context_t	c,
		reme_surface_t	s,
		reme_volume_t	v
	)

Colorize surface vertices using the color information stored in the reconstruction volume.

Colorizes all vertices of the given surface. Before calling this method you need to at least generate a surface using reme_surface_generate. It's possible to use a modified version of the surface. E.g you can even pass a poisson-reconstructed surface.

Vertices with missing color information receive a unique color which is currently green (in RGBA: 0/255/0/0). Use the reme_surface_inpaint_vertices to generate missing vertex colors.

Parameters

c	A valid context object
s	A valid surface object
v	A valid volume object

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_NO_COLOR_SUPPORT	Setup does not support colors.
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_colorize.cpp, and example_reconstructmesdk_point_and_shoot_with_colors.cpp.

reme_error_t reme_surface_inpaint_vertices	(	reme_context_t	c,
		reme_surface_t	s
	)

Paint missing vertex colors.

Vertices without a valid vertex color will be painted by an algorithm that tries to use surrounding color information. A vertex is said to have no color or an invalid color if the color is exactly green (in RGBA: 0/255/0/0).

Parameters

c	A valid context object
s	A valid surface object

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_NO_COLOR_SUPPORT	Setup does not support colors.
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_colorize.cpp, and example_reconstructmesdk_point_and_shoot_with_colors.cpp.

reme_error_t reme_surface_get_points	(	reme_context_t	c,
		reme_surface_t	s,
		const float **	coordinates,
		int *	length
	)

Get points of a surface.

The surface points are represented as an array of floats where each point consists of 4 coordinates Px Py Pz Pw Px Py Pz Pw ... . The w component is always zero.

Note the i-th point starts at index i * 4 of coordinate array returned.

Memory Management Rules Exception

The returned coordinates pointer remains valid until the mesh changes.

Parameters

c	A valid context object
s	A valid surface object
coordinates	A mutable pointer to constant point data.
length	The number of coordinates returned. To get the number of points divide this value by 4.

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

reme_error_t reme_surface_get_normals	(	reme_context_t	c,
		reme_surface_t	s,
		const float **	coordinates,
		int *	length
	)

Get point normals of a surface.

The surface point normals are represented as an array of floats where each point consists of 4 coordinates Px Py Pz Pw Px Py Pz Pw ... . The w component is always zero.

Note the i-th point normal starts at index i * 4 of coordinate array returned.

Memory Management Rules Exception

The returned coordinates pointer remains valid until the mesh changes.

Parameters

c	A valid context object
s	A valid surface object
coordinates	A mutable pointer to constant point normal data.
length	The number of coordinates returned. To get the number of point normals divide this value by 4.

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

reme_error_t reme_surface_get_vertex_colors	(	reme_context_t	c,
		reme_surface_t	s,
		const float **	coordinates,
		int *	length
	)

Get colors of surface vertices.

The surface vertex colors are represented as an array of floats where each color consists of 4 coordinates R G B A R G B A ... . The A component is always zero. The range of each channel is between zero and one.

Note the i-th color starts at index i * 4 of coordinate array returned. The returned array might be empty if no colors are have been generated through reme_surface_colorize_vertices or colors are not supported by the current setup. Vertices that don't have a valid color will carry an invalid color represented as 0 1 0 0 .

Memory Management Rules Exception

The returned coordinates pointer remains valid until the mesh changes.

Parameters

c	A valid context object
s	A valid surface object
coordinates	A mutable pointer to constant color data.
length	The number of coordinates returned. To get the number of colors divide this value by 4.

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

reme_error_t reme_surface_get_triangles	(	reme_context_t	c,
		reme_surface_t	s,
		const unsigned int **	indices,
		int *	length
	)

Get triangle faces of a surface.

The triangle faces are represented as an array of unsigned integers (point indice s) where each triangle consists of 3 indices that represent that points that make up each face P0 P1 P2 P0 P1 P2 ... .

Note the i-th triangle starts at index i * 3 of index array returned.

Memory Management Rules Exception

The returned indices pointer remains valid until the mesh changes.

Parameters

c	A valid context object
s	A valid surface object
indices	A mutable pointer to constant triangle index data.
length	The number of indices returned. To get the number of triangles divide this value by 3.

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

reme_error_t reme_surface_save_to_file	(	reme_context_t	c,
		reme_surface_t	s,
		const char *	filename
	)

Export the surface to file.

The exporter is chosen based on the file extension. Currently supported are

• .PLY - Polygon File Format
• .STL - StereoLithography
• .OBJ - Wavefront
• .3DS - 3D Studio Max

Parameters

c	A valid context object
s	A valid surface object
filename	Filename to save mesh as

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_colorize.cpp, example_reconstructmesdk_one_minute.cpp, example_reconstructmesdk_point_and_shoot_with_colors.cpp, example_reconstructmesdk_sensor_multi_independent.cpp, example_reconstructmesdk_sensor_printing.cpp, and example_reconstructmesdk_surface.cpp.