Surface

Detailed Description

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);

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

  // Close holes through Poisson reconstruction using custom parameters
  reme_options_t o;
  reme_options_create(c, &o);

  reme_surface_bind_poisson_options(c, m, o);
  reme_options_set(c, o, "depth", "7");  
  reme_surface_poisson(c, m);

  // Reduce mesh down to 20k triangles
  reme_surface_bind_decimation_options(c, m, o);
  reme_options_set(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);

  // Transform the mesh from world space to CAD space, so external viewers
  // can cope better with the result.

  float mat[16];
  reme_transform_set_predefined(c, REME_TRANSFORM_WORLD_TO_CAD, mat);
  reme_surface_transform(c, m, mat);

  // 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 sensor 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_one_minute.cpp, example_reconstructmesdk_options_lazy.cpp, example_reconstructmesdk_options_type_safe.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_one_minute.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];
  optional bool enable_clipping = 6 [default = false];
}

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_lazy.cpp, 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 decimantion options
message decimation_options {
  optional int32 maximum_faces = 1 [default = 100000];
  optional int32 maximum_vertices = 2 [default = 0];
  optional float maximum_error = 3 [default = 100000];
}

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_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.

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_one_minute.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.

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_decimate	(	reme_context_t	c,
		reme_surface_t	s
	)

Decimate the extracted 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_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

Examples:

example_reconstructmesdk_surface.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_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_one_minute.cpp, and example_reconstructmesdk_surface.cpp.