Interactive 3D slides

5. GUI with ImGui

This example displays an implicit surface (a sum of blobs and of Perlin noise), meshed by marching cubes at each change of its parameters. The interface is the ImGui window of the program, so that all the settings are in a single window and there is no HTML to write. In a slide, this window has to be readable on the projector, and to stay consistent with the buttons of the slide.

Get this example

Download: c6-cgp-marching-cubes.zip. The zip contains the C++ program, its slide in reveal.js (slides.html) and in lhtml-site (lhtml-site/), the web build of the demo (ready to show), the bridge and the build script. The CGP project is needed only to recompile.

Try it: unzip it, and in the unzipped folder run python3 -m http.server 8080; then open http://localhost:8080/examples/c6-cgp-marching-cubes/slides.html, the slide with its demo. To change the program: build and run.

Graphics: a scalar field, marching cubes, recomputed liveInterface: ImGui, and buttons in the slide
Live: the buttons change the same variables as the ImGui window, which shows the new values.

What is new

  • ImGui readable on the projector: ?gui_scale=1.4 enlarges its text, through project::gui_scale, which the template of CGP gives to ImGui at each frame. Its sections stay closed at start: a long window goes out of the frame.
  • The same variables for ImGui and the slide: they are declared to the bridge, with what to recompute when the slide changes them. ImGui shows the new values at the next frame, as it reads them.
  • Two controls hidden on the web: the wireframe (glPolygonMode, see example 4) and the export of the mesh to a file, which would land in the memory of the page.
  • Mouse: in CGP, ImGui takes the clicks over its window; elsewhere the mouse turns the camera.

Build and run

As example 3, with c6-cgp-marching-cubes.

Rem. The marching cubes of this example come from an example of epita_ani3d_lab_code-2027.

The files

examples/c6-cgp-marching-cubes/src/
  scene.cpp, scene.hpp            the scene, and the parameters declared to the bridge
  main.cpp                        the main() of the template, plus slide::parse
  implicit_surface/               the field, the marching cubes, and the ImGui window (gui_helper.cpp)

src/scene.cpp

scene.cpp: the declarations are at the end of initialize().

Show the full file: scene.cpp (94 lines)
// Origin: the CGP example of github.com/drohmer/epita_ani3d_lab_code-2027
// (examples/02_marching_cubes/02_marching_cube_dynamic), as in the documentation of CGP.
// interactive-3d-slides: the parameters declared to the bridge (end of initialize()), the size of the
// ImGui window set from the slide, and two controls hidden on the web (gui_helper.cpp).
#include "scene.hpp"
#include "slide_bridge.hpp"


using namespace cgp;




void scene_structure::initialize()
{
	camera_control.initialize(inputs, window); // Give access to the inputs and window global state to the camera controler
	camera_control.set_rotation_axis_y();
	// interactive-3d-slides: farther than the original { 3.0f, 2.0f, 2.0f }, so that the whole domain fits a wide slide
	camera_control.look_at({ 6.0f, 4.5f, 3.5f }, {0,0,0}, {0,0,1});
	global_frame.initialize_data_on_gpu(mesh_primitive_frame());


	// Initialization for the Implicit Surface
	// ***************************************** //

	// interactive-3d-slides: the same variables as the ImGui window, declared to the bridge. The slide
	// changes them (address of the iframe, postMessage, slide-controls.js); the ImGui window
	// shows the new values by itself at the next frame, as it reads the variables.
	// Their values given at start (?isovalue=0.3) are applied here, before the first field.
	auto refield = [this] {
		implicit_surface.set_domain(gui.domain.samples, gui.domain.length);
		implicit_surface.update_field(field_function, gui.isovalue);
	};
	slide::param("isovalue", gui.isovalue, 0.0f, 1.0f, 0.01f)
		.on_change([this] { implicit_surface.update_marching_cube(gui.isovalue); });
	slide::param("power_c", field_function.sc, 0.0f, 2.0f, 0.05f).with_label("power C").on_change(refield);
	slide::param("noise", field_function.noise_magnitude, 0.0f, 1.0f, 0.05f).on_change(refield);
	slide::param("samples", gui.domain.samples, 8, 100).on_change(refield);
	slide::param("domain", gui.display.domain).with_label("box");
	// size of the text of ImGui: larger in a slide (?gui_scale=1.6), read by the template at each frame
	slide::param("gui_scale", project::gui_scale, 0.5f, 3.0f, 0.1f).with_label("ImGui size");

	refield();
}



void scene_structure::display_frame()
{
	// Update the camera view matrix from the camera controller
	environment.camera_view = camera_control.camera_model.matrix_view();

	// Set the light to the current position of the camera
	environment.light = camera_control.camera_model.position();
	
	// The standard frame
	if (gui.display.frame)
		draw(global_frame, environment);

	if (gui.display.surface)    // Display the implicit surface
		draw(implicit_surface.drawable_param.shape, environment);

	if (gui.display.wireframe) // Display the wireframe of the implicit surface
		draw_wireframe(implicit_surface.drawable_param.shape, environment, { 0,0,0 });

	if (gui.display.domain)    // Display the boundary of the domain
		draw(implicit_surface.drawable_param.domain_box, environment);

}

void scene_structure::display_gui()
{
	// Handle the gui values and the updates using the helper methods (*)
	implicit_surface.gui_update(gui, field_function);
}

void scene_structure::mouse_move_event()
{
	if (!inputs.keyboard.shift)
		camera_control.action_mouse_move();
}
void scene_structure::mouse_click_event()
{
	camera_control.action_mouse_click();
}
void scene_structure::keyboard_event()
{
	camera_control.action_keyboard();
}
void scene_structure::idle_frame()
{
	camera_control.idle_frame();
}

src/implicit_surface/gui_helper.cpp

The ImGui window; the two controls hidden on the web are marked with the comment interactive-3d-slides:. gui_helper.cpp

Show the full file: gui_helper.cpp (63 lines)
#include "gui_helper.hpp"

using namespace cgp;

void display_gui_implicit_surface(bool& is_update_field, bool& is_update_marching_cube, bool& is_save_obj, gui_parameters& gui, field_function_structure& field_function)
{
	if (ImGui::CollapsingHeader("Display"))
	{
		ImGui::Checkbox("Frame", &gui.display.frame);
		ImGui::Checkbox("Surface", &gui.display.surface);
#ifndef __EMSCRIPTEN__
		// interactive-3d-slides: draw_wireframe uses glPolygonMode, which WebGL does not have
		ImGui::Checkbox("Wireframe", &gui.display.wireframe);
#endif
		ImGui::Checkbox("Domain", &gui.display.domain);
	}

	if (ImGui::CollapsingHeader("Domain"))
	{
		is_update_field |= ImGui::SliderInt("Samples", &gui.domain.samples, 8, 100);

		is_update_field |= ImGui::SliderFloat("Lx", &gui.domain.length.x, 0.5f, 10.0f);
		is_update_field |= ImGui::SliderFloat("Ly", &gui.domain.length.y, 0.5f, 10.0f);
		is_update_field |= ImGui::SliderFloat("Lz", &gui.domain.length.z, 0.5f, 10.0f);
	}

	if (ImGui::CollapsingHeader("Field Function"))
	{
		ImGui::Text("Position A");
		is_update_field |= ImGui::SliderFloat("Power A", &field_function.sa, 0.0f, 2.0f);
		is_update_field |= ImGui::SliderFloat("Pa-x", &field_function.pa.x, -2.0f, 2.0f);
		is_update_field |= ImGui::SliderFloat("Pa-y", &field_function.pa.y, -2.0f, 2.0f);
		ImGui::Spacing();
		ImGui::Text("Position B");
		is_update_field |= ImGui::SliderFloat("Power B", &field_function.sb, 0.0f, 2.0f);
		is_update_field |= ImGui::SliderFloat("Pb-x", &field_function.pb.x, -2.0f, 2.0f);
		is_update_field |= ImGui::SliderFloat("Pb-y", &field_function.pb.y, -2.0f, 2.0f);
		ImGui::Spacing();
		ImGui::Text("Position C");
		is_update_field |= ImGui::SliderFloat("Power C", &field_function.sc, 0.0f, 2.0f);
		is_update_field |= ImGui::SliderFloat("Pc-x", &field_function.pc.x, -2.0f, 2.0f);
		is_update_field |= ImGui::SliderFloat("Pc-y", &field_function.pc.y, -2.0f, 2.0f);
		ImGui::Spacing();
		ImGui::Text("Noise parameters");
		is_update_field |= ImGui::SliderFloat("Noise Power", &field_function.noise_magnitude, 0.0f, 1.0f);
		is_update_field |= ImGui::SliderFloat("Noise Scale", &field_function.noise_scale, 0.1f, 2.5f);
		is_update_field |= ImGui::SliderFloat("Noise offset", &field_function.noise_offset, -3, 3);
		is_update_field |= ImGui::SliderInt("Noise Octave", &field_function.noise_octave, 1, 8);
		is_update_field |= ImGui::SliderFloat("Noise Persistance", &field_function.noise_persistance, 0.1f, 0.5f);
	}

	ImGui::Spacing();
	is_update_marching_cube |= ImGui::SliderFloat("Isovalue", &gui.isovalue, 0.0f, 1.0f);

#ifndef __EMSCRIPTEN__
	// interactive-3d-slides: on the web, the file would be written in the memory of the page
	ImGui::Spacing();
	is_save_obj = ImGui::Button("Export mesh as obj");
#else
	(void)is_save_obj;
#endif

}
The other files: main.cpp, scene.hpp, implicit_surface.cpp/.hpp, field_function.cpp/.hpp
// CGP library
#include "cgp/cgp.hpp"

// Running application
#include "application.hpp"

// Custom scene of this code
#include "scene.hpp"

// interactive-3d-slides: the parameters of the demo, set from the slide
#include "slide_bridge.hpp"


int main(int argc, char* argv[])
{
	// The only change to the main() of the template: keep the arguments
	// (--isovalue 0.3 ..., given by the address of the iframe)
	slide::parse(argc, argv);

	scene_structure scene;
	application_structure app;
	app.initialize(argv[0], &scene);

	app.start_loop();

	return 0;
}
#pragma once


#include "cgp/cgp.hpp"
#include "environment.hpp"

#include "implicit_surface/implicit_surface.hpp"
#include "implicit_surface/gui_helper.hpp"

using cgp::mesh_drawable;


// The structure of the custom scene
struct scene_structure : cgp::scene_inputs_generic {
	
	// ****************************** //
	// Elements and shapes of the scene
	// ****************************** //
	camera_controller_orbit_euler camera_control;
	camera_projection_perspective camera_projection;
	window_structure window;

	mesh_drawable global_frame;          // The standard global frame
	environment_structure environment;   // Standard environment controler
	input_devices inputs;                // Storage for inputs status (mouse, keyboard, window dimension)
	gui_parameters gui;                  // Standard GUI element storage
	
	// ****************************** //
	// Elements and shapes of the scene
	// ****************************** //

	implicit_surface_structure implicit_surface; // Structures used for the implicit surface (*)
	field_function_structure field_function;     // A Parametric function used to generate the discrete field (*)

	// ****************************** //
	// Functions
	// ****************************** //

	void initialize();    // Standard initialization to be called before the animation loop
	void display_frame(); // The frame display to be called within the animation loop
	void display_gui();   // The display of the GUI, also called within the animation loop


	void mouse_move_event();
	void mouse_click_event();
	void keyboard_event();
	void idle_frame();

};
#pragma once

#include "cgp/cgp.hpp"
#include "field_function.hpp"
#include "gui_helper.hpp"



// All the data used for the Implicit Surface 
// ********************************************** //

// Sub-structure that contains the discrete field data
struct implicit_surface_field_structure {
	cgp::spatial_domain_grid_3D domain;   // The domain where the discrete field is defined
	cgp::grid_3D<float> field;            // The grid storing the value of the field
	cgp::grid_3D<cgp::vec3> gradient;     // The discrete gradient of the field
};

// Sub-structure that contains the data of the surface
struct implicit_surface_data {
	size_t number_of_vertex;              // The valid number of vertex of the surface
	std::vector<cgp::vec3> position;      // Positions of the mesh
	std::vector<cgp::vec3> normal;        // Normals of the mesh
	std::vector<cgp::marching_cube_relative_coordinates> relative; // Relative coordinates of the vertices expressed as an edge in the discrete grid 
};

// Sub-structure that contains the elements that are displayed
struct implicit_surface_drawable_structure {
	cgp::triangles_drawable shape;     // Structure used to display the geometry
	cgp::curve_drawable domain_box;    // Structure used to display the box
};


// Global structure 
struct implicit_surface_structure 
{	
	implicit_surface_data data_param;
	implicit_surface_drawable_structure drawable_param;
	implicit_surface_field_structure field_param;	


	// Helpers functions that should be called in the scene
	// *************************************************** //

	//   Recompute from scratch the field and the marching cube
	void update_field(field_function_structure const& field_function, float isovalue);

	//   Recompute only the marching cube for a different isovalue (while minimize re-allocations)
	void update_marching_cube(float isovalue);

	//   Helper function to quickly set the domain (number of samples, and dimensions)
	void set_domain(int samples, cgp::vec3 const& length);
	
	//   Helper function to update the gui and call the associated update functions
	void gui_update(gui_parameters& gui, field_function_structure& field_function);
};


// Compute a grid filled with the value of some scalar function - the size of the grid is given by the domain
cgp::grid_3D<float> compute_discrete_scalar_field(cgp::spatial_domain_grid_3D const& domain, field_function_structure const& func);

// Compute the gradient of the scalar field using finite differences on the voxels
cgp::grid_3D<cgp::vec3> compute_gradient(cgp::grid_3D<float> const& field);
#include "implicit_surface.hpp"


using namespace cgp;




static void update_normals(std::vector<vec3>& normals, int number_of_vertex, grid_3D<vec3> const& gradient, std::vector<marching_cube_relative_coordinates> const& relative_coords)
{
	// Compute the normal using linear interpolation of the gradients
	for (int k = 0; k < number_of_vertex; ++k)
	{
		size_t const idx0 = relative_coords[k].k0;
		size_t const idx1 = relative_coords[k].k1;

		vec3 const& n0 = gradient.data[idx0];
		vec3 const& n1 = gradient.data[idx1];

		float const alpha = relative_coords[k].alpha;
		normals[k] = -normalize((1 - alpha) * n0 + alpha * n1, { 1,0,0 });
	}
}

void implicit_surface_structure::update_marching_cube(float isovalue)
{
	// Variable shortcut
	std::vector<vec3>& position = data_param.position;
	std::vector<vec3>& normal = data_param.normal;
	size_t& number_of_vertex = data_param.number_of_vertex;
	spatial_domain_grid_3D const& domain = field_param.domain;
	std::vector<cgp::marching_cube_relative_coordinates> relative_coord = data_param.relative;
	grid_3D<float> const& field = field_param.field;
	grid_3D<vec3> const& gradient = field_param.gradient;

	// Store the size of the previous position buffer
	size_t const previous_size = position.size();

	// Compute the Marching Cube
	number_of_vertex = marching_cube(position, field.data.data, domain, isovalue, &relative_coord);

	// Resize the vector of normals if needed
	if (normal.size() < position.size())
		normal.resize(position.size());

	update_normals(normal, number_of_vertex, gradient, relative_coord);

	// Update the display of the mesh
	if (position.size() > previous_size) {
		// If there is more position than allocated - perform a full clear and reallocation from scratch
		drawable_param.shape.clear();
		drawable_param.shape.initialize_data_on_gpu(position, normal);
	}
	else {
		// Otherwise simply update the new relevant values re-using the allocated buffers
		drawable_param.shape.vbo_position.update(position, number_of_vertex);
		drawable_param.shape.vbo_normal.update(normal, number_of_vertex);
		drawable_param.shape.vertex_number = number_of_vertex;
	}

}



void implicit_surface_structure::update_field(field_function_structure const& field_function, float isovalue)
{
	// Variable shortcut
	grid_3D<float>& field = field_param.field;
	grid_3D<vec3>& gradient = field_param.gradient;
	spatial_domain_grid_3D& domain = field_param.domain;

	// Compute the scalar field
	field = compute_discrete_scalar_field(domain, field_function);

	// Compute the gradient of the scalar field
	gradient = compute_gradient(field);

	// Recompute the marching cube
	update_marching_cube(isovalue);

	// Reset the domain visualization (lightweight - can be cleared at each call)
	drawable_param.domain_box.clear();
	drawable_param.domain_box.initialize_data_on_gpu(domain.export_segments_for_drawable_border());
}

void implicit_surface_structure::set_domain(int samples, cgp::vec3 const& length)
{
	field_param.domain = spatial_domain_grid_3D::from_center_length({ 0,0,0 }, length, samples * int3{ 1,1,1 });
}



void implicit_surface_structure::gui_update(gui_parameters& gui, field_function_structure& field_function)
{
	bool is_update_marching_cube = false;
	bool is_update_field = false;
	bool is_save_obj = false;

	display_gui_implicit_surface(is_update_field, is_update_marching_cube, is_save_obj, gui, field_function);

	if (is_update_marching_cube) 
		update_marching_cube(gui.isovalue);
	if (is_update_field) {
		set_domain(gui.domain.samples, gui.domain.length);
		update_field(field_function, gui.isovalue);
	}

	if (is_save_obj) {
		data_param.position.resize(data_param.number_of_vertex);
		data_param.normal.resize(data_param.number_of_vertex);
		mesh_save_file_obj("mesh.obj", data_param.position, data_param.normal);
	}
		
}



grid_3D<float> compute_discrete_scalar_field(spatial_domain_grid_3D const& domain, field_function_structure const& func)
{
	grid_3D<float> field;
	field.resize(domain.samples);

	// Fill the discrete field values
	for (int kz = 0; kz < domain.samples.z; kz++) {
		for (int ky = 0; ky < domain.samples.y; ky++) {
			for (int kx = 0; kx < domain.samples.x; kx++) {

				vec3 const p = domain.position({ kx, ky, kz });
				field(kx, ky, kz) = func(p);

			}
		}
	}

	return field;
}



grid_3D<vec3> compute_gradient(grid_3D<float> const& field)
{
	grid_3D<vec3> gradient;
	gradient.resize(field.dimension);

	int const Nx = field.dimension.x;
	int const Ny = field.dimension.y;
	int const Nz = field.dimension.z;

	// Use simple finite differences
	//  g(k) = g(k+1)-g(k) // for k<N-1
	//  otherwise g(k) = g(k)-g(k-1)

	for (int kz = 0; kz < Nz; ++kz) {
		for (int ky = 0; ky < Ny; ++ky) {
			for (int kx = 0; kx < Nx; ++kx) {

				vec3& g = gradient(kx, ky, kz);
				float const f = field(kx, ky, kz);

				g.x = kx != Nx - 1 ? field(kx + 1, ky, kz) - f : f - field(kx - 1, ky, kz);
				g.y = ky != Ny - 1 ? field(kx, ky + 1, kz) - f : f - field(kx, ky - 1, kz);
				g.z = kz != Nz - 1 ? field(kx, ky, kz + 1) - f : f - field(kx, ky, kz - 1);

			}
		}
	}

	return gradient;
}
#pragma once

#include "cgp/cgp.hpp"

// Parametric function defined as a sum of blobs-like primitives
//  f(p) = sa exp(-||p-pa||^2) + sb exp(-||p-pb||^2) + sc exp(-||p-pc||^2) + noise(p)
//   with noise: a Perlin noise
// The operator()(vec3 p) allows to query a value of the function at arbitrary point in space
struct field_function_structure {

	// Query the value of the function at any point p
	float operator()(cgp::vec3 const& p) const;


	// ***************************//
	// Parameters
	// ***************************//

	// The 3 center of the 3 blobs
	cgp::vec3 pa = {  1.0f, 0.0f, 0.0f};
	cgp::vec3 pb = { -1.0f, 0.0f, 0.0f };
	cgp::vec3 pc = {  0.0F, 0.5f, 0.0f };

	// The magnitude associated to each primitive
	float sa = 1.0f;
	float sb = 1.0f;
	float sc = 0.0f; // note: The third blob is not visible initially has its magnitude is 0

	// The parameters of the Perlin noise
	float noise_magnitude   = 0.0f; // Magnitude of the noise
	float noise_offset      = 0.0f; // An offset in the parametric domain (get a different value of noise with same parameters)
	float noise_scale       = 1.0f; // Scale in the parametric domain
	int noise_octave        = 5;    // Maximum number of octave
	float noise_persistance = 0.3f; // Persistence of Perlin noise
};
#include "field_function.hpp"

using namespace cgp;

// Parameterization Gaussian centered at point p0
static float gaussian(vec3 const& p, vec3 const& p0, float sigma)
{
	float const d = norm(p - p0);
	float const value = std::exp(-(d * d) / (sigma * sigma));
	return value;
}

float field_function_structure::operator()(cgp::vec3 const& p) const
{
	float value = 0.0f;
	value += sa * gaussian(p, pa, 1.0f);
	value += sb * gaussian(p, pb, 1.0f);
	value += sc * gaussian(p, pc, 1.0f);

	if (noise_magnitude > 0) {
		vec3 const offset = vec3{ noise_offset + 1000, 1000, 1000 };
		vec3 const p_noise = noise_scale * p + offset;
		value += noise_magnitude * noise_perlin(p_noise, noise_octave, noise_persistance);
	}

	return value;
}
#pragma once

#include "cgp/cgp.hpp"
#include "field_function.hpp"

// Element of the GUI that are not already stored in other structures
struct gui_parameters {

	struct { // Elements that are displayed
		bool frame = false;
		bool wireframe = false; // Display the wireframe of the implicit surface
		bool surface = true;    // Display the implicit surface
		bool domain = true;     // Display the box representing the domain of the marching cube
	} display;

	struct { // Elements of the domain
		int samples = 30;
		cgp::vec3 length = { 5,3,3 };
	} domain;

	// Isovalue used during the marching cube
	float isovalue = 0.5f;
};


void display_gui_implicit_surface(bool& is_update_field, bool& is_update_marching_cube, bool& is_save_obj, gui_parameters& gui, field_function_structure& field_function);

slides.html

slides.html

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Marching cubes</title>
<!--
  A slide of reveal.js with the demo of this example. Open it through a web server, from the root of
  the repository: python3 -m http.server 8080, then http://localhost:8080/examples/c6-cgp-marching-cubes/slides.html
  reveal.js comes from a CDN: for a talk without network, download it next to this file.
-->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/reveal.js@5.1.0/dist/reveal.css">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/reveal.js@5.1.0/dist/theme/white.css">
<style>
  .reveal iframe.demo { width: 100%; height: 540px; border: 0; }
  .reveal .row { font-size: 0.6em; margin-top: 12px; }
  .reveal .row button { font: inherit; padding: 4px 14px; margin: 0 4px; border-radius: 8px;
                        border: 2px solid #999; background: white; cursor: pointer; }
  .reveal .row button.on { background: #333; color: white; border-color: #333; }
</style>
</head>
<body>
<div class="reveal"><div class="slides">
<section>
  <h3>Marching cubes</h3>
  <iframe class="demo" id="demo" data-src="web/index.html?gui_scale=1.4"></iframe>
  <div class="row">
    <button data-demo-set="power_c=1.2">Third blob</button>
    <button data-demo-set="isovalue=0.3">Larger</button>
    <button data-demo-set="power_c=0&amp;isovalue=0.5">Back</button>
  </div>
</section>
</div></div>
<script src="https://cdn.jsdelivr.net/npm/reveal.js@5.1.0/dist/reveal.js"></script>
<script src="../../bridge/slide-controls.js"></script>
<script>Reveal.initialize({hash: true});</script>
</body>
</html>

lhtml-site/

The same slide in lhtml-site (open it), organized as in example 1; only the slide changes, src/01_marching-cubes/index.html.j2:

{% set layout = 'side' %}

= Marching cubes

* Marching cubes on a scalar field, recomputed at each change
* The interface is the ImGui window of the program, enlarged: `?gui_scale=1.4`

<div class="controls">
<p>
<button data-demo-set="power_c=1.2">Third blob</button>
<button data-demo-set="isovalue=0.3">Larger</button>
<button data-demo-set="power_c=0&amp;isovalue=0.5">Back</button>
</p>
</div>

media::
demo::../_demo/index.html?gui_scale=1.4(.live)
img::../_demo/poster.png(.still)
::

Next: 6. Values sent back to the slide.