Daniel Sieger

Connected Components of a Polygon Mesh

2026-01-01T00:00:00+00:00

In mesh processing, we often assume ideal 2-manifold meshes consisting of a single connected component. In practice, however, meshes can be more complex: a single object may actually consist of many disconnected components, as shown in the image above.

Depending on your application, you may need to detect these components for further filtering or processing. I recently added connected component detection to PMP. This article provides a concise, practical overview of the algorithm and is also a good exercise for learning to work with meshes.

I’ll first outline the general algorithm, describe the C++ implementation, and show how to test it. I’ll also briefly demonstrate how to visualize components using color-coding. Finally, I’ll filter components for further downstream processing.

Basic Algorithm

The algorithm is based on a breadth-first traversal of the vertex graph. Starting from a seed vertex, it incrementally discovers all vertices connected to that seed. Here’s some pseudo-code:

for each vertex

  if vertex not yet visited
    mark vertex as visited
    push vertex to queue

  while queue not empty
    pop vertex from queue

    for each neighbor vertex
      if neighbor not yet visited
        mark neighbor as visited
        push neighbor to queue

Here’s an image illustrating the principle: starting from a seed vertex, all connected neighbors are visited incrementally.

Here, connected components are defined with respect to vertex adjacency: two vertices are connected if they share an edge. In other words, components are computed on the vertex graph induced by mesh edges. Face-connected components can be computed similarly by traversing face adjacency.

C++ Implementation

Now let’s implement this in C++ using PMP. I left out some details in the pseudo-code that are essential for a practical implementation. In particular, we want to keep track of the current component index and remember which vertex belongs to which component. The function should also return the number of components so that callers can easily check if there are multiple components present. Here’s the full implementation:

int connected_components(SurfaceMesh& mesh)
{
  // add component as vertex property
  auto component = mesh.add_vertex_property<int>("v:component", -1);

  // index to track current component
  int idx = 0;

  for (auto v : mesh.vertices())
  {
    if (component[v] != -1)
      continue;

    std::queue<Vertex> vertices;
    component[v] = idx;
    vertices.push(v);

    while (!vertices.empty())
    {
      auto vv = vertices.front();
      vertices.pop();

      // visit neighboring vertices
      for (auto vc : mesh.vertices(vv))
      {
        if (component[vc] == -1)
        {
          component[vc] = idx;
          vertices.push(vc);
        }
      }
    }

    // increment component index
    idx++;
  }

  // return number of components
  return idx;
}

Note that vertices not connected to any other vertex are detected as individual connected components. This naturally follows from the algorithm being based on vertex adjacency.

Testing

Let’s verify that the algorithm works. The simplest test case is a mesh with a single component:

SurfaceMesh mesh;
auto v0 = mesh.add_vertex(Point(0, 0, 0));
auto v1 = mesh.add_vertex(Point(1, 0, 0));
auto v2 = mesh.add_vertex(Point(0, 1, 0));
mesh.add_triangle(v0, v1, v2);

auto nc = connected_components(mesh);

assert(nc == 1);

That works. Now let’s add two disconnected triangles:

SurfaceMesh mesh;
auto v0 = mesh.add_vertex(Point(0, 0, 0));
auto v1 = mesh.add_vertex(Point(1, 0, 0));
auto v2 = mesh.add_vertex(Point(0, 1, 0));
mesh.add_triangle(v0, v1, v2);

v0 = mesh.add_vertex(Point(2, 0, 0));
v1 = mesh.add_vertex(Point(3, 0, 0));
v2 = mesh.add_vertex(Point(2, 1, 0));
mesh.add_triangle(v0, v1, v2);

auto nc = connected_components(mesh);

assert(nc == 2);

Works as well. For a more practical and realistic test case I’ll generate multiple mixed polygon meshes and combine them into a single mesh. For that I need a helper function to append one mesh to another:

auto append = [](const SurfaceMesh& source, SurfaceMesh& dest) {
  std::map<Vertex, Vertex> vertex_map;
  for (auto v : source.vertices())
  {
    Vertex new_v = dest.add_vertex(source.position(v));
    vertex_map[v] = new_v;
  }
  for (auto f : source.faces())
  {
    std::vector<Vertex> face_vertices;
    for (auto v : source.vertices(f))
    {
      face_vertices.push_back(vertex_map[v]);
    }
    dest.add_face(face_vertices);
  }
};

Now you can generate a few randomly placed spheres, combine them into a single mesh, and make sure to detect the right number of components:

SurfaceMesh mesh;
for (int i = 0; i < 10; ++i)
{
  Scalar x = rand() / (Scalar)RAND_MAX;
  Scalar y = rand() / (Scalar)RAND_MAX;
  Scalar z = rand() / (Scalar)RAND_MAX;

  auto sphere = uv_sphere(Point(x, y, z), 0.1, 25, 25);

  append(sphere, mesh);
}
auto nc = connected_components(mesh);
assert(nc == 10);

Visualization

If you want to visualize the individual components you can assign a color based on the component index to the mesh faces:

const auto n_components = connected_components(mesh);
auto face_colors = mesh.face_property<Color>("f:color");
auto component = mesh.vertex_property<int>("v:component");

// create a color map
std::map<int, Color> component_colors;
for (int i = 0; i < n_components; ++i)
{
  float r = (rand() / (float)RAND_MAX);
  float g = (rand() / (float)RAND_MAX);
  float b = (rand() / (float)RAND_MAX);
  component_colors[i] = Color(r, g, b);
}

// assign face colors
for (auto f : mesh.faces())
{
  // determine component index from any face vertex
  const auto v = mesh.vertices(f);
  const auto idx = component[*v];
  face_colors[f] = component_colors[idx];
}

Here we are, detecting connected components and visualizing them using color-coding:

Filtering

Depending on your application, you may want to filter the detected components based on some criterion. The approach is similar to the color-coding example above: first run component detection, then filter according to your chosen criterion. As an example, we’ll extract the largest component, using the bounding box size as a simple metric that works even for meshes with boundaries.

First, let’s split all components into separate meshes. I’m intentionally using this explicit approach for demonstration purposes and because the functionality itself might be useful in other cases.

auto split = [](SurfaceMesh& mesh) -> std::vector<SurfaceMesh> {
  const auto nc = connected_components(mesh);
  std::vector<SurfaceMesh> meshes(nc);
  auto component = mesh.vertex_property<int>("v:component");

  // one vertex map per component
  std::vector<std::map<Vertex, Vertex>> vertex_maps(nc);

  for (const auto f : mesh.faces())
  {
    // determine component from any face vertex
    const auto v = mesh.vertices(f);
    const int idx = component[*v];

    std::vector<Vertex> face_vertices;
    face_vertices.reserve(mesh.valence(f));

    for (const auto vv : mesh.vertices(f))
    {
      auto& vmap = vertex_maps[idx];

      // create vertex only once per component
      if (vmap.find(vv) == vmap.end())
      {
        Vertex new_v = meshes[idx].add_vertex(mesh.position(vv));
        vmap[vv] = new_v;
      }

      face_vertices.push_back(vmap[vv]);
    }

    meshes[idx].add_face(face_vertices);
  }
  return meshes;
};

All that’s left to do is to determine the largest component. I’m using bounding box size for simplicity, adjust accordingly if you want to check for area or volume.

// assume that mesh has several components of varying size
auto meshes = split(mesh);
int largest = 0;
Scalar max_size = -std::numeric_limits<Scalar>::max();
for (size_t i = 0; i < meshes.size(); i++)
{
  const auto size = bounds(meshes[i]).size();
  if (size > max_size)
  {
    max_size = size;
    largest = i;
  }
}

Hope this helps!

Public Drafts With Jekyll

2025-12-31T00:00:00+00:00

I’m using Jekyll, a static site generator, to build this website¹. I always have a number of work-in-progress draft posts floating around, some being merely vague ideas, others close to being ready for publication.

Jekyll natively supports working with drafts: files you keep in your _drafts folder are not built by default. They are only included in the build when you explicitly tell Jekyll to do so, either by using the --drafts option when building the site or by specifying

show_drafts: true

in your _config.yml.

Publishing Drafts

Sometimes, I’d like to include one or more drafts in the published site to send the link to someone for review. Other blogging engines might refer to this as private posts. There are several ways to achieve this. I’ll outline three methods:

Building drafts
Hiding a regular post
Using a custom collection

Building Drafts

You can enable building drafts either by specifying the --drafts option or setting show_drafts: true in your _config.yml. By default, this will include all your drafts in the listing of your blog posts, and that’s probably not what you want. Somewhere in your site you probably have a loop over all posts that lists them, something like this:

<ul>
{% for post in site.posts %}
  <li><a href="{{ post.url }}">{{ post.title }}</a></li>
{% endfor %}
</ul>

You need to modify this loop to exclude drafts. This is straightforward: drafts in Jekyll already have a draft variable set to true when building drafts is enabled. All you need to do is add a simple check for it:

<ul>
{% for post in site.posts %}
  {% unless post.draft %}
  <li><a href="{{ post.url }}">{{ post.title }}</a></li>
  {% endunless %}
{% endfor %}
</ul>

If you have an RSS feed, you should exclude drafts there as well:

<!-- feed boilerplate -->
{% for post in site.posts %}
  {% unless post.draft %}
    <entry>
      <title>{{ post.title }}</title>
      <link href="{{ site.url }}{{ post.url }}"/>
      <updated>{{ post.date | date_to_xmlschema }}</updated>
      <id>{{ site.url }}{{ post.id }}</id>
      <content type="html">{{ post.content | xml_escape }}</content>
    </entry>
  {% endunless %}
{% endfor %}

Note that if you are using the jekyll-sitemap plugin you will want to exclude drafts from there as well. You can do this by setting sitemap: false in the front matter for each draft, but of course that’s a tedious manual procedure and prone to errors. There’s also a certain risk of forgetting to remove the variable when publishing the post. The last method I present here has a more robust solution to this problem.

Hiding Regular Posts

This is a relatively straightforward method if you only want to include specific posts that are ready for review. Instead of building drafts, you just treat the draft as a regular post and put it in your _posts folder. Then you simply add the draft front matter variable:

---
title: Your Draft Title
draft: true
---

In order to hide the post, you follow exactly the same procedure as above: exclude posts with the draft front matter variable from your post listings, feed, and sitemap.

The major advantage of this approach is that it is more fine-grained: Instead of building and publishing all drafts, you only include those you want to publish for review.

Custom Collection

This is probably the most advanced method, but it allows for greater flexibility. Basically, drafts are a collection, and you can customize how this particular collection is processed. Let’s start by defining the drafts collection in _config.yml:

collections:
  drafts:
    output: true
    permalink: /:collection/:name

Next, we want to make sure that the drafts collection uses the post layout by default and is automatically excluded from the sitemap:

defaults:
  - scope:
      path: "_drafts"
    values:
      layout: "post"
      sitemap: false

The good thing is that Jekyll still treats those posts as drafts for filtering purposes: they have the draft variable defined, so you can exclude them from post listings or feeds as shown above. You can even add a possibly hidden drafts.md page to only list your drafts:

---
layout: page
title: Drafts
description: "Draft articles"
sitemap: false
---

<ul>
{% for post in site.drafts %}
  <li><a href="{{ post.url }}">{{ post.title }}</a></li>
{% endfor %}
</ul>

Voilà!

I’m building my site using GitHub pages, so I’m stuck with Jekyll 3.X for now. All testing for this article was done using Jekyll 3.9.5. ↩

Digital Detox

2025-12-30T00:00:00+00:00

Earlier this year, after reading Cal Newport’s Digital Minimalism, I decided to go on a digital detox for a period of 30 days. I stopped reading my usual news outlets, minimized smartphone usage, and avoided social media entirely.

I really enjoyed the silence.

Now that this period is over, I’ve started visiting some news sites again, although in a much more focused and targeted way. My smartphone stays tucked away most of the time, with notifications off or Do Not Disturb enabled. Even though my smartphone use was already minimal, intentionally keeping it out of reach and out of sight helped me a lot to reduce distractions and maintain better focus.

When it comes to social media, I went one step further: I deleted all my accounts. Reddit, Mastodon, LinkedIn, Discord, and whatnot—all gone for good, and I’m not looking back.

I was never a heavy social media user to begin with. Still, over time, a surprising number of accounts had accumulated, each offering questionable value. More often than not, they led to distraction and procrastination rather than supporting meaningful work, learning, or interaction with others.

This is not an argument that these platforms provide no value at all. They clearly do; otherwise, they would not attract and retain so many users. Their mechanisms and incentives are well understood. However, I largely agree with Newport’s core argument: marginal value alone is not a sufficient justification for adopting or retaining a digital tool. If a tool consumes attention without providing significant benefit, its net effect may still be negative.

Leaving LinkedIn Behind

Deleting my LinkedIn profile was the most difficult decision, as it has the greatest professional impact. More than a decade of accumulated professional and academic contacts carries a certain weight. Letting go of the fear of missing out wasn’t easy: the hypothetical recruiter with the perfect opportunity, or the concern that not having a profile might reflect poorly during a job search. These risks may or may not be real, but I’m willing to accept them.

The key for me was some honest reflection about what value these tools actually provided. The answer was: close to zero. I realized that I could not recall more than a handful of genuinely meaningful or useful interactions on any of these platforms. Perhaps there was occasional feedback on a blog post, but that was about it. What I do recall is a steady drain on time and attention. In that light, the decision became easier.

Where Attention Goes

Your mileage may vary, but for now I prefer to invest my time and attention elsewhere: into work that compounds, projects that are intrinsically rewarding, and social interactions in the real world. For me, this is less about abstinence and more about intention: choosing where my attention goes, and creating the conditions for sustained focus and meaningful work.

If any of this resonates with you, Cal Newport’s Digital Minimalism is well worth reading. Trying a short, time-boxed digital detox can be a useful experiment to question habits and discover what matters to you. With the New Year just around the corner, it’s the perfect time to try.

Code Coverage with CMake and CTest

2024-08-03T00:00:00+00:00

In this article, I’ll walk you through the steps for adding code coverage testing using CMake and CTest. This is an addition to my previous article on code coverage testing for C++. Integrating basic coverage testing with CMake has become a lot easier since then.

The pre-requisites are the same: I’m assuming CMake as a build system and gcc or clang as compiler.

A Minimal Setup

Let’s start with some minimal example code:

// main.cpp

#include <cassert>

int max(int a, int b) {
    if (a > b) {
        return a;
    }
    return b;
}

int main() {
    assert(max(1, 0) == 1);
}

Next, add a basic CMakeLists.txt file for compiling the code:

cmake_minimum_required(VERSION 3.20)
project(coverage_test)

# make sure to use a Debug build
set(CMAKE_BUILD_TYPE "Debug")

# define executable target
add_executable(coverage_test main.cpp)

Use the standard steps to build using CMake:

mkdir build && cd build && cmake .. && cmake --build .

This should give you something like this:

[ 50%] Building CXX object CMakeFiles/coverage_test.dir/main.cpp.o
[100%] Linking CXX executable coverage_test
[100%] Built target coverage_test

Congratulations!

Adding Coverage Support

There are three steps required to add code coverage testing to the setup:

Add the required compiler and linker flags
Enable CTest
Add your executable as a test

Both clang and gcc only need a single option to enable generation of coverage information: -coverage. However, you need to add this to both your compiler and linker flags:

target_compile_options(coverage_test PRIVATE -coverage)
target_link_options(coverage_test PRIVATE -coverage)

I’d recommend using the more modern variant of specifying options per target instead of using global options using add_compile_options or add_link_options. The PRIVATE scope limits the options only for compiling this target.

Enabling CTest just requires

include(CTest)

Finally, in order to register your executable as a test you need to add

add_test(NAME coverage COMMAND coverage_test)

This needs to come after defining the executable target. The full CMakeLists.txt now looks like this:

cmake_minimum_required(VERSION 3.20)
project(coverage)

# include CTest support
include(CTest)

# define executable target
add_executable(coverage_test main.cpp)

# make sure to use a Debug build
set(CMAKE_BUILD_TYPE "Debug")

# compile with coverage options
target_compile_options(coverage_test PRIVATE -coverage)
target_link_options(coverage_test PRIVATE -coverage)

add_test(NAME coverage COMMAND coverage_test)

Generating Coverage Information

Re-build the project:

cmake .. && cmake --build .

Run your test with ctest:

ctest -T Test

Generate coverage information:

ctest -T Coverage

This should give you something like this as output:

Performing coverage
   Processing coverage (each . represents one file):
    .
   Accumulating results (each . represents one file):
    .
        Covered LOC:         7
        Not covered LOC:     1
        Total LOC:           8
        Percentage Coverage: 87.50%

You can also combine the two steps into a single call to ctest:

ctest -T Test -T Coverage

You can also verify that additional tests increase your coverage by adding another assertion to your main() function:

assert(max(0, 1) == 1);

Wipe out any outdated coverage information:

find . -name '*.gcda' -delete

Re-run the whole thing:

cmake --build . && ctest -T Test -T Coverage

Congratulations! You achieved 100% code coverage:

Performing coverage
   Processing coverage (each . represents one file):
    .
   Accumulating results (each . represents one file):
    .
        Covered LOC:         9
        Not covered LOC:     0
        Total LOC:           9
        Percentage Coverage: 100.00%

What’s Next?

This setup doesn’t provide you with a nice way to visualize which parts of the code are covered. However, this can be achieved either by using lcov as described in my previous article, or by using an extension for your IDE to directly visualize the coverage information in your editor. The Gcov Viewer for VS Code seems to be a popular choice, but I did not test it yet.

Hope this helps!

Opaque Pointer Pattern in C++

2024-08-02T00:00:00+00:00

I’m doing a lot of code re-design and refactoring these days. One challenge is to change the implementation of a class or module while maintaining a stable interface for its clients. The ability to replace an old implementation with a new one without changing other parts of the code is extremely useful to ensure the correctness of the new implementation: it allows you to run integration tests with the new implementation and hunt down any bugs or regressions.

The opaque pointer design pattern is extremely useful in this situation. Maybe you’re familiar with it as pointer-to-implementation idiom or compiler firewall. It is also described as Bridge Pattern in the GoF book¹.

This article walks you through the basics of the pattern and shows you how to implement it using std::unique_ptr.

What’s the Problem?

The basic problem is that C++ class declarations expose private details of the class. Private member functions and data members need to be declared in the header. Here’s an example for illustration:

// Point.h

class Point
{
public:
  Point(float x, float y);
  float x();
  float y();

private:
  float x_;
  float y_;
};

While users of this class don’t have direct access to the private data members x_ and y_, there is still a dependency: If you change the private implementation details of Point, all other compilation units that include Point.h know about the change and need to be re-compiled.

This only gets worse for more complex dependency chains, e.g., when there are dependencies to other classes internal to the module that need to be included. To a certain degree, this can be dealt with by using forward declarations. However, at the end of the day there is an information leak: Private implementation details are leaking to clients. This goes directly against the idea of information hiding.

The opaque pointer pattern helps to deal with this problem.

Hiding Behind a Pointer

The basic idea of the opaque pointer pattern is to hide the details of the implementation behind a pointer to an incomplete type. Picking up the Point example from above, a basic version might look like this:

// Point.h

class Point
{
public:
  Point(float x, float y);
  float x();
  float y();

private:
  struct Impl;  // forward-declaration of the implementation
  Impl* impl;   // pointer to implementation
};

As you can see, the header file only contains a forward-declaration and a pointer to an incomplete type. This doesn’t tell anything about how the point class actually stores its data. This decision is left to the implementation file:

// Point.cpp
// There's a problem in this example. Can you spot it?

#include "Point.h"

struct Point::Impl
{
  float x;
  float y;
};

Point::Point(float x, float y)
{
  impl = new Point::Impl();
  impl->x = x;
  impl->y = y;
}

float Point::x()
{
  return impl->x;
}

float Point::y()
{
  return impl->y;
}

Note how Point::Impl is only defined in the implementation file. You can now change the implementation of Point without changing the API defined in the header. Let’s say you prefer a std::array instead of two floats:

// Point.cpp
// There's still a problem in this example. Can you spot it?

#include "Point.h"

#include <array>

struct Point::Impl
{
  std::array<float, 2> data;
};

Point::Point(float x, float y)
{
  impl = new Point::Impl();
  impl->data[0] = x;
  impl->data[1] = y;
}

float Point::x()
{
  return impl->data[0];
}

float Point::y()
{
  return impl->data[1];
}

Voilà! Same interface, different implementation.

This is clearly a step forward in terms of information hiding. However, the example above has some problems, as already hinted at in the comments. I used a raw pointer to the Point::Impl struct, allocated in the Point constructor. However, I never delete it. Ouch!

Instead of fixing the above example by using manual memory management, let’s look into an alternative implementation using std::unique_ptr.

Opaque Pointer with `std::unique_ptr`

C++11 came with smart pointer classes that allow you to avoid memory management issues like the above. In particular, std::unique_ptr is a smart pointer has unique ownership semantics of the resource it manages and automatically takes care of object destruction. Let’s give this a try:

// Point.h

#include <memory>

class Point
{
public:
  Point(float x, float y);
  float x();
  float y();

private:
  struct Impl;                 // forward-declaration of the implementation
  std::unique_ptr<Impl> impl;  // pointer to implementation
};

Aww, too bad, doesn’t compile out of the box:

unique_ptr.h:66:19: error: invalid application of 'sizeof' to an incomplete type 'Point::Impl'
  static_assert(sizeof(_Tp) >= 0, "cannot delete an incomplete type");
                ^~~~~~~~~~~
unique_ptr.h:300:7: note: in instantiation of member function 'std::default_delete<Point::Impl>::operator()' requested here
    __ptr_.second()(__tmp);
    ^
unique_ptr.h:266:75: note: in instantiation of member function 'std::unique_ptr<Point::Impl>::reset' requested here
  _LIBCPP_INLINE_VISIBILITY _LIBCPP_CONSTEXPR_SINCE_CXX23 ~unique_ptr() { reset(); }

Looks like the compiler is trying to do something on an incomplete type, which doesn’t work out. What’s actually missing here is a destructor required for std::unique_ptr doing its job.

Fine, let’s add a destructor to Point:

// Point.h

class Point
{
  //...
  ~Point() = default; // error
  //...
}

Too bad, still doesn’t compile, but the compiler hints are a little more useful now:

Point.h:34:5: note: in instantiation of member function
'std::unique_ptr<Point::Impl>::~unique_ptr' requested here
  ~Point() = default;  // error

What’s going on? In order to use a std::unique_ptr class member, we need a destructor being available. However, the defaulted destructor in the header is not sufficient because Impl is still an incomplete type. What’s actually needed is:

A destructor declared in the header file.
A destructor defined in the implementation in file.

The destructor declaration becomes

// Point.h
class Point
{
  // ...
  ~Point();
  // ...
}

and in the implementation file we add

// Point.cpp
Point::~Point() = default;

Putting this all together, we finally have a working implementation of the opaque pointer pattern using std::unique_ptr. Yay!

To round this up, let’s briefly review some pros and cons.

Advantages

The main advantage obviously is better information hiding: Private implementation details are not exposed to the users of a class. Even more, consistent usage of opaque pointers can be used to ensure binary compatibility, although I didn’t try that in practice, yet.

Another advantage are reduced compilation dependencies. If you ever worked with a large C++ code base you probably know how annoying long compile times can get. The more definitions you have in your headers the more dependencies you have and the more compilation units need to be re-compiled upon a change. Consistent use of opaque pointers and forward declarations can help to mitigate this problem.

Drawbacks

Everything has a cost, and this pattern is no exception. There are two main points to consider:

Implementation overhead
Run-time overhead

As for (1), consistently using this pattern can be a chore and requires engineering discipline in your team. Code reviews and checklists help.

As for (2), there is a certain overhead involved: at least one level of indirection de-referencing the Impl pointer. This can be a no-go for performance-critical code. However, I’d consider the main application of opaque pointers to be in higher-level APIs that provides access to more complex and performance-critical functions of a deep module.

Wrapping up

After reading this article, you should understand the basics of the opaque pointer pattern and how you can implement it using std::unique_ptr. I also gave some hints on when it is appropriate to use it and when maybe not.

Admittedly, this article is only scratching the surface of the subject. There’s more to say about opaque pointers, notably when it comes to moving and copying things around. I’ll save that for another day.

PMP Library Version 3.0 Released

2023-08-24T00:00:00+00:00

We just released version 3.0 of PMP, the Polygon Mesh Processing Library. This is a major version with several additions and API changes. Highlights include:

A polygon Laplacian operator allowing several algorithms to work on general polygon meshes, including smoothing, parameterization, fairing, and curvature computation.
The geodesics in heat method has been added.
The algorithms API has been revamped to use a simple function-based interface.
New interactive online demos integrated into the algorithms guide.
We no longer use git submodules for handling third-party dependencies.
Upgrade C++ standard to C++17
… a whole lot of smaller fixes, cleanups, and improvements

See the official release announcement and the changelog for a full summary of changes.

API Simplicity

2023-08-06T00:00:00+00:00

I recently simplified the PMP algorithms API. This was a somewhat embarrassing but also very rewarding experience. Embarrassing because the old code was just absurd in some cases. Rewarding because it made me question some deeply ingrained habits. In fact, this exercise changed my approach to API design.

Want the short version? Here it is: Stop writing classes, use functions.

Now, that’s of course too simple. Read on for the full story.

Complex Class Interfaces

Up until the 2.x releases, we were using classes as the primary interface for algorithms. The main reason was convenience and consistency. This led to some absurd usage patterns like this:

SurfaceSubdivision(mesh).loop();

This:

auto mesh = SurfaceFactory::icosahedron();

Or this:

SurfaceSimplification simplifier(mesh);
simplifier.initialize();
simplifier.simplify(0.1 * mesh.n_vertices());

This type of interface looks highly familiar to anyone used to OOP style APIs. In fact, I always had the filter interfaces of VTK in mind when designing the original API. Even though this interface might be familiar, I wouldn’t call it simple.

Simple Functions

It turns out, however, that none of our algorithms actually needs a class-based interface. Plain and simple functions are fully sufficient, and the resulting API is much cleaner, leaner, and easier to use:

auto mesh = icosahedron();
loop_subdivision(mesh);
decimate(mesh, 0.1 * mesh.n_vertices());

Of course the above example is somewhat artificial, but I think you get the spirit. Straightforward code, less typing, uniform usage.

Another benefit is that a simple function-based interface exposes far fewer implementation details in the headers files. And all that without resorting to constructions like the Pimpl idiom.

Reducing API Surface

The next step was to reduce the functionality exposed in the public API. Some folks call this the API surface, and I think it’s a useful analogy. It is important to realize that every externally observable behavior of your API will eventually be used and relied upon. The more dependencies you have the harder it gets to change and maintain your code over time. Therefore, one of your goals should be to keep your API surface small.

In case of PMP, the implementations of complex algorithms like remeshing or decimation make use of several helper classes such as a TriangleKdTree or a Quadric class. In the past, we used to make those helpers public, just in case someone might have a use for it. YAGNI at work. There’s absolutely no need to expose those helpers in the public API. Now they are all neatly tucked away in the implementation files of their respective algorithms.

Focus on Singular Use Cases

Another common pitfall is to provide too many variants of algorithms. When you have an implementation of a well-known algorithm floating around, it’s always tempting to just add it to the library, just in case someone might need it. YAGNI again. However, this can lead to a large collection of algorithms with only half of them working correctly. Plus, your maintenance cost increases constantly.

What I prefer instead is to have one algorithm implementation for a specific task. Example: We now have loop_subdivision() for triangle meshes,catmull_clark_subdivision() for quad meshes, and quad_tri_subdivision() for mixed meshes. And that’s it. No need for three different triangle mesh subdivision schemes.

Don’t Misuse Inheritance

Even though I advocate for using functions above, classes and OOP still have their place. Inheritance is a key principle of OOP but it can be easily misused. This can be the case when using inheritance for purely technical reasons, code re-use, or out of convenience and laziness. If your inheritance does not represent an is-a relationship, you should be skeptical.

In our library, the SurfaceMeshGL class responsible for rendering meshes was inheriting from the core SurafaceMesh data structure. The main reason was just code reuse and convenience. It was convenient to have direct access to the SurfaceMesh internals. It was convenient to have a single SurfaceMeshGL member in all viewer classes and to modify the mesh through the SurfaceMesh API.

However, this construction was in clear contradiction to SOLID principles, in particular the single responsibility principle. It introduced tight coupling where none was required.

I am now using an independent Renderer class that only has a single responsibility, and I use composition in the viewer classes instead of relying on inheritance. Basic stuff, I know.

Bottom Line

Striving for simplicity always has been one of the primary design goals for PMP. However, things can get lost along the way. It remains a challenge to keep things simple over time.

There’s more work to come. I’m not yet happy with all aspects of the API, and there are other areas of doubtful complexity such as the inheritance hierarchy of the viewer classes.

References and Further Reading

C++ Member Functions vs. Free Functions

2023-05-01T00:00:00+00:00

As a C++ programmer, you are probably familiar with the following design question: Should you implement a function as a class member or as a free function?

Not so sure about the answer? Well, let’s examine.

An Example

Here’s an example from the mesh processing library I’m working on. Let’s say you have a class SurfaceMesh for representing polygon meshes and you want to add a function that reads a mesh from different file formats.

You basically have two obvious options.

Either you add a class member:

class SurfaceMesh {
    ...
    void read(const std::filesystem::path& file);
}

Or you use a free function:

void read(SurfaceMesh& mesh, const std::filesystem::path& file);

Which option would you choose?

In the past, we used to have a member function, mostly for sake of convenience. It’s easy to discover, type, and remember. Problem solved?

SurfaceMesh mesh;
mesh.read("file.obj");

Well, not so fast. This might be the obvious solution, but it’s not necessarily the best way from a software design perspective.

In fact, there are very solid arguments for preferring free functions. Here are just a few:

Loose Coupling: A free function is more loosely coupled to the class it is operating on. It only depends on the interface. This also enables generic functions being usable with different concrete classes.
Encapsulation and Hiding: A free function promotes encapsulation and information hiding since it does not have access to the implementation details of the class.
Flexibility and Extensibility: Adding another free function is cheap and easy and does not require modification of the class definition.
Testing: A free function is generally easier to test due to increased independence. No hacks required to test those pesky private member functions.

And the list goes on. In fact, there is an excellent talk by Klaus Iglberger going through this question in detail. He basically argues that free functions are the preferable choice in most cases. Notably, free functions help to follow SOLID principles.

Along similar lines, Herb Sutter also recommends free functions in his C++ Coding Standards. Scott Meyers also favors free functions in Effective C++ item 23. He even came up with an algorithm to decide when to use a free function or a member function: Given a class C and a function f related to C, use the following algorithm:

if (f needs to be virtual)
{
    make f a member function of C;
}
else if (f is operator>> or operator<<)
{
    make f a non-member function;
    if (f needs access to non-public members of C)
    {
        make f a friend of C;
    }
}
else if (f needs type conversions on its left-most argument)
{
    make f a non-member function;
    if (f needs access to non-public members of C)
    {
        make f a friend of C;
    }
}
else
{
    make f a member function of C;
}

Admittedly, there are some advantages of member functions as well. For some folks they just might be easier to use. In particular, you get better IDE support for auto-completion when typing something like mesh. in the example above. There’s also a little less ambiguity since there’s at least one function argument less to worry about.

Conclusions

In general, preferring free functions seems like a very reasonable choice. I think the main counter-argument is usability and discovery. However, there also is a proposal by Bjarne Stroustrup and Herb Sutter for a unified function call syntax that would allow to simply write

mesh.read("file.stl");

if there is a function with the signature

read(Mesh mesh, const std::string& filename)

While this certainly would add some convenience, I’m not entirely sure it’s worth the added complexity. It’s not that C++ doesn’t already have enough of that!

Let me close by saying that in practice the choice is not always that obvious. There might be cases when you design an API around free functions only to later realize that some function does indeed needs access to the internals of the class. This has been exactly the case in the motivating example above, and so I resorted to a friend function. 😕

References and Further Reading

Free Your Functions by Klaus Iglberger
C++ Coding Standards by Herb Sutter and Andrei Alexandrescu
Effective C++ by Scott Meyers
Unified Call Syntax Proposal by Bjarne Stroustrup and Herb Sutter

A Framework for Better Documentation

2023-04-24T00:00:00+00:00

I recently came across an awesome framework for creating better technical documentation: The Diátaxis framework developed by Daniele Procida. It is a well-structured system that you can immediately apply to improve your software documentation. The basic idea goes like this.

Four Types of Documentation

The framework distinguishes between four fundamental types of documentation.

Tutorials
Guides
Reference
Explanation

Each type of documentation is geared towards a specific audience and purpose.

Tutorials

The main goal of a tutorial is to help beginners getting started. The focus is on learning and acquiring the competencies required to use the software. The tutorial should contain step-by-step instructions. Each step should be easily attainable and provide concrete, meaningful results. The structure should be clear and linear. After completing the tutorial, the user should be ready to work with the other parts of the documentation to proceed his learning.

Audience: Beginners
Purpose: Learning

Guides

How-to guides contain precise directions how to achieve a specific goal using the software. In contrast to learning-oriented tutorials, a guide is a form of task-oriented documentation. The user has a concrete question in mind, such as “How do I write a mesh to a file?”. A guide already assumes a certain degree of familiarity with the subject area. Unnecessary details can be omitted. The goal is not to give the full picture. The focus is on helping the user while he is working with the software.

Audience: Intermediate
Purpose: Problem-solving

Reference

This is the technical reference documentation that describes in detail how the machinery works. In case of a software library, this is most likely the API reference. The main goal of this type of documentation is information. To support this, it should be very concise and to the point. However, this should also include common pitfalls to be aware of.

Audience: Experienced
Purpose: Information retrieval

Explanation

This is the more detailed background material that further clarifies the understanding of the software. An in-depth overview of the design of a library might be a good example. Something you’re interested in when you want to understand the internals of the system. Might also go by the names background, discussion, or conceptual guides.

Audience: Experts, developers
Purpose: Understanding

Wrapping Up

Obviously, I’m only scratching the surface here. If you want to dive deeper, have a look at the full description at diataxis.fr. There is also a conference presentation by Daniele Procida on the same subject.

Overall, the framework looks very well thought out to me. At least, it made me think about adapting documentation towards specific audiences and keeping their needs in mind. I hope I’ll find some time to put this into practice for PMP.

Hope this helps!

Dieter Rams: Ten Principles for Good Design

2023-03-31T00:00:00+00:00

Simply inspiring, always giving me new impulses: Ten principles for good design by Dieter Rams.

Good Design is Innovative

The possibilities for innovation are not, by any means, exhausted. Technological development is always offering new opportunities for innovative design. But innovative design always develops in tandem with innovative technology, and can never be an end in itself.

Good Design Makes a Product Useful

A product is bought to be used. It has to satisfy certain criteria, not only functional but also psychological and aesthetic. Good design emphasizes the usefulness of a product while disregarding anything that could possibly detract from it.

Good Design is Aesthetic

The aesthetic quality of a product is integral to its usefulness because products are used every day and have an effect on people and their well-being. Only well-executed objects can be beautiful.

Good Design Makes a Product Understandable

It clarifies the product’s structure. Better still, it can make the product talk. At best, it is self-explanatory.

Good Design is Unobtrusive

Products fulfilling a purpose are like tools. They are neither decorative objects nor works of art. Their design should therefore be both neutral and restrained, to leave room for the user’s self-expression.

Good Design is Honest

It does not make a product more innovative, powerful or valuable than it really is. It does not attempt to manipulate the consumer with promises that cannot be kept.

Good Design is Long-Lasting

It avoids being fashionable and therefore never appears antiquated. Unlike fashionable design, it lasts many years – even in today’s throwaway society.

Good Design is Thorough Down to the Last Detail

Nothing must be arbitrary or left to chance. Care and accuracy in the design process show respect towards the user.

Good Design is Environmentally Friendly

Design makes an important contribution to the preservation of the environment. It conserves resources and minimizes physical and visual pollution throughout the lifecycle of the product.

Good Design is as Little Design as Possible

Less, but better – because it concentrates on the essential aspects, and the products are not burdened with non-essentials.

Back to purity, back to simplicity.

Source: https://www.vitsoe.com/gb/about/good-design

License: Creative Commons CC-BY-NC-ND 4.0 licence

C++17 Nested Namespaces

2023-02-18T00:00:00+00:00

Nested namespaces used to be somewhat cumbersome in C++. You had to repeat the namespace keyword and by default each namespace resulted in an extra level of indentation:

namespace pmp {
    namespace algorithms {
        namespace subdivision {
            // ...
            // your code here
            // ...
        }
    }
}

With a bit of tweaking, you could teach your IDE or clang-format to avoid the indentation:

namespace pmp {
namespace algorithms {
namespace subdivision {
    // ...
    // your code here
    // ...
}
}
}

Still, this always felt cumbersome to me.

With C++17 you can write this much more compact manner:

namespace pmp::algorithms::subdivision {
    // ...
    // your code here
    // ...
}

Admittedly, this is a relatively minor feature addition in C++17. However, now that I had a chance to use it I don’t want to miss it anymore.

Hope this helps!

PMP Library Version 2.0 Released

2022-08-15T00:00:00+00:00

We just released version 2.0 of PMP, the Polygon Mesh Processing Library. This is a major version with several additions and improvements as well as some API changes. Highlights include:

Support for texture seams in SurfaceSimplification
A new quad/triangle subdivision scheme
A new SurfaceFactory class for generating basic shapes
Error reporting using exceptions
Improved compatibility with the STL and CGAL
Additional rendering capabilities
Switch to C++14

See the official release announcement and the changelog for a full summary of changes.

Your Code Doesn't Have to Be a Mess

2022-07-25T00:00:00+00:00

Fools ignore complexity. Pragmatists suffer it. Some can avoid it. Geniuses remove it. - Alan Perlis

If you’ve been developing software for a while, you know that code has this natural tendency to turn into a mess. Keeping software simple over time is a challenge that keeps me thinking. My last post left you hanging without much concrete advice. This time I will outline a few high-level strategies to keep software simple.

Define Clear Goals

Define clear goals what problem your software is trying to solve. Write them down, keep them visible. Always keep them in mind when making decisions about adding a new feature or accepting a proposed change. Do one thing and do it well. Don’t try to solve a myriad of problems at the same time. Follow basic Unix philosophy.

Setup Constraints

Define your non-goals as well: What problems does your software explicitly not solve? Constrain the scope of your software. Setup technical constraints on programming languages, libraries, or models of computation you are using. Embrace those constraints and stick to them. They will force you to think harder about the problem at hand. Get creative within the bounds of your constraints. Working with constraints can foster creativity and innovation. However, be aware when you need to bend your code too much.

Say No

There is almost always an infinite demand for new features and functionality. Learning to say no is crucial to keep your software from growing wildly into too many directions. This can be super tough or downright impossible, notably in a commercial context. But even then: Do what is needed, but not more. Be aware of feature creep. But also be aware of when saying no would be unreasonable.

Eliminate Waste

Regularly pare down your code, and be relentless while doing it. Remove any unused features, dead code, debugging helpers, or prototype code used during development. Version control has your back. Eliminating waste is a core principle of lean software development. Borderline but fun: Only accept PRs that reduce net code size for a while. Be aware of code obfuscation though.

Minimize Dependencies

Be picky about adding any dependencies. Don’t treat code re-use as a holy grail. Carefully consider the pros and cons. Dependencies might break, disappear, turn into garbage, or become a security risk. Consider to vendor by default. If the functionality in question is crucial for your core business: Consider doing it yourself.

Closing Remarks

Obviously, the above strategies are not equally applicable in all settings. Your mileage may vary a lot between commercial development, an open source project, or creative coding.

Similarly, striving for simplicity can be much harder if you are working on software that tackles complex problems. Some problem domains have an inherent complexity that can not be negotiated away. However, even in those cases you can strive for simplicity in the building blocks of your complex system.

If you are developing software on a team, there is also an important social dimension. Some folks just revel in complexity, and it can be tough to develop a sense for simplicity with them. I’ve got the suspicion that the C++ crowd is particularly vulnerable to this disposition, but that’s another story.

Finally, keep in mind that simplicity is not a value by itself. It is a means to an end: produce better software, and be able to maintain and evolve it over time.

References and Further Reading

Simple Made Easy by Rich Hickey
Unix philosophy
Lean software development
Epigrams in Programming by Alan Perlis
Clean Code by Robert C. Martin
A Philosophy of Software Design by John Ousterhout

The discussion on HackerNews makes an interesting read, thanks to all participants!

Keep it Simple, Over Time

2022-03-30T00:00:00+00:00

Perhaps you already heard of the KISS principle. It’s an acronym for “keep it simple, stupid”. It states that most systems work best if kept simple. It’s a guiding principle in software engineering to favor simple solutions over complex ones.

Simplicity as a design goal is one aspect of the KISS principle. I think another aspect is even more important, and that’s the temporal one:

Keep it simple, over time.

Coming up with a clean and lean design for a new project is already a challenge. Keeping things simple over time is a much bigger challenge due to the different forces at play at different points in time. New features, bug fixes, workarounds, engineering and business tradeoffs. They all make it extremely hard to maintain simplicity.

Do I have an easy solution to this challenge? Sorry, not this time. It’s a question that makes me think. And I invite you to think about it as well.

How do you keep things simple, over time?

Code Coverage Testing for C++

2022-03-06T00:00:00+00:00

Do you have unit tests for your code? Yes? Awesome!

Do you know how much of your code is executed by your tests? No?

Aww, don’t feel bad!

This is what code coverage testing is for: it gives you detailed information on how much of your code base is covered by your test suite.

This post describes how to add code coverage testing to your C++ project. I’m assuming you are using CMake as build system and GCC or Clang as compiler.

What’s Code Coverage?

Code coverage tells you which parts of your code are executed by your test suite and—even more important—which parts are not. The coverage rate is typically specified as a percentage of files, functions, blocks, or lines being covered.

Code coverage works by instrumenting your code so that the resulting executable will generate statistics on which code paths are executed how many times. You can visualize the coverage information in different forms, such as a HTML report, in your CI system, or your IDE.

Why Use Code Coverage?

The main goal of code coverage testing to provide insight which parts of your code get tested. This increases confidence in your test suite. You can make sure that important code paths are properly executed by your tests. It shows if all branches are triggered or if there are corner cases left untested.

A second advantage is that it helps to avoid redundancy. Without any information which code is triggered by a test, you are likely to run certain code paths over and over again. This contradicts the goal of having a test suite that runs fast, which is a key requirement for efficient testing.

Getting Started

I’ll proceed in three steps:

Command line usage
CMake integration
Continuous integration

For command line usage, I’ll use the Gcov code coverage analysis tool. Both GCC and Clang can generate profiling information that can be processed by Gcov.

Let’s start with this simple example C++ code:

#include <cassert>

int max(int a, int b) {
    if (a > b) {
        return a;
    }
    return b;
}

int main() {
    assert(max(1, 0) == 1);
}

Compile this with the -coverage flag to tell the compiler to instrument the code:

clang++ -O0 -coverage test.cpp && ./a.out

Note that disabling optimizations is required to get reliable coverage results, hence the -O0 flag. After running the test program, you’ll see two additional files being generated:

$ ls test.*
test.cpp        test.gcda       test.gcno

The .gcda and .gcno files contain the coverage data. Now run gcov to process the results:

$ gcov test.cpp
File 'test.cpp'
Lines executed:87.50% of 8
Creating 'test.cpp.gcov'

Nice! This tells us that we already cover 87.5% of our lines of code. Not too bad, but there’s room for improvement.

The resulting test.cpp.gcov file gives a more detailed breakdown which lines have been executed how many times:

        -:    0:Source:test.cpp
        -:    0:Graph:test.gcno
        -:    0:Data:test.gcda
        -:    0:Runs:1
        -:    0:Programs:1
        -:    1:#include <cassert>
        -:    2:
        1:    3:int max(int a, int b) {
        1:    4:    if (a > b) {
        1:    5:        return a;
        -:    6:    }
    #####:    7:    return b;
        1:    8:}
        -:    9:
        1:   10:int main() {
        1:   11:    assert(max(1, 0) == 1);
        1:   12:}

Not surprisingly, our little test here does not trigger all branches of the max() function. Let’s fix that by adding another assertion:

int main() {
    assert(max(1, 0) == 1);
    assert(max(0, 1) == 1);
}

This bumps up our line coverage to 100%:

$ gcov test.cpp
File 'test.cpp'
Lines executed:100.00% of 9
Creating 'test.cpp.gcov'

Next, let’s have a look how to visualize this information in a more accessible manner.

Generate a HTML Report

Checking code coverage for a simple example like above is easy. However, for a larger project you want something to visualize the coverage information in a more convenient manner. In particular, identifying parts of the code which are not yet covered is important.

This is where lcov comes in: it is a graphical fronted to your coverage data. In particular, you can use it to generate HTML reports. This is done in two steps. First, run lcov in the directory with the coverage information:

lcov --directory . --capture --output-file coverage.info

Then generate the HTML files:

genhtml --demangle-cpp -o coverage coverage.info

Open the resulting coverage/index.html file in a browser of your choice and you’ll see an overview like this:

This allows you to locally browse through your code base and check which parts are covered (light blue) and which not (orange).

Note that I’m showing the version for the lower coverage rate here.

CMake Integration

For convenience, you can integrate the report generation directly into your build system. Here’s a basic CMakeLists.txt file that adds a custom coverage target to run lcov and genhtml:

cmake_minimum_required(VERSION 3.6)
project(coverage-example)

if(ENABLE_COVERAGE)
  # set compiler flags
  set(CMAKE_CXX_FLAGS "-O0 -coverage")

  # find required tools
  find_program(LCOV lcov REQUIRED)
  find_program(GENHTML genhtml REQUIRED)

  # add coverage target
  add_custom_target(coverage
    # gather data
    COMMAND ${LCOV} --directory . --capture --output-file coverage.info
    # generate report
    COMMAND ${GENHTML} --demangle-cpp -o coverage coverage.info
    WORKING_DIRECTORY ${CMAKE_BINARY_DIR})
endif()

add_executable(test test.cpp)

Configure and build the project with the ENABLE_COVERAGE option:

cmake -DENABLE_COVERAGE=true .. && make

Now you can run the executable and generate the HTML report:

./test && make coverage

Continuous Integration

You can take coverage testing one step further and directly integrate it into your continuous integration (CI) pipeline. This is useful for checking how the coverage rate evolves and to make sure it does not decrease as you integrate new features into your project.

In this example, I’m using GitHub Actions for integration builds and the Coveralls web service to visualize results.

Here is an example for a GitHub workflow that builds and runs the example project from above and uploads the coverage results to Coveralls:

name: coverage
on: push
env:
  BUILD_TYPE: Debug
jobs:
  coverage:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v2

      - name: Install dependencies
        if: runner.os == 'Linux'
        run: sudo apt-get install -o Acquire::Retries=3 lcov

      - name: Create build directory
        run: cmake -E make_directory ${{runner.workspace}}/build

      - name: Configure CMake
        shell: bash
        working-directory: ${{runner.workspace}}/build
        run: cmake $GITHUB_WORKSPACE -DCMAKE_BUILD_TYPE=$BUILD -DENABLE_COVERAGE=true

      - name: Build
        working-directory: ${{runner.workspace}}/build
        shell: bash
        run: cmake --build . --config $BUILD_TYPE

      - name: Run
        working-directory: ${{runner.workspace}}/build
        shell: bash
        run: ./test

      - name: Coverage
        working-directory: ${{runner.workspace}}/build
        shell: bash
        run: make coverage

      - name: Coveralls
        uses: coverallsapp/github-action@master
        with:
          path-to-lcov: ${{runner.workspace}}/build/coverage.info
          github-token: ${{ secrets.GITHUB_TOKEN }}

If you are curious what the result looks like for a real-world project, check out the Coveralls page for our mesh processing library.

Bottom Line

Code coverage testing is a tremendously useful tool that I regularly use during development. When writing new code, it gives me confidence that my tests are doing what I think they do. However, I find it particularly useful when bringing legacy code under test. The coverage information guides me which tests to write until I reach sufficient coverage for that code.

Beware though that using code coverage as a quality metric can be misleading. High coverage is not a goal in itself. It’s a means, not an end. The fact that there is a test triggering your code does not guarantee you anything about wether the test does something meaningful at all.

Give code coverage a try. I bet that once you experience the benefit of having coverage information available you don’t want to miss it form your development toolbox.

C++ Trailing Return Types

2022-01-28T00:00:00+00:00

The other day, I was modernizing the PMP library code using clang-tidy. One of the suggestions was to use trailing function return types. I didn’t look too close at this C++11 feature before. Read on for a brief introduction and a summary of pros and cons.

What’s This?

Trailing return types are an alternative syntax introduced in C++11 to declare the return type of a function. In the old form you specify the return type before the name of the function:

int max(int a, int b);

With the new syntax you write auto before the function name and specify the return type after the function name and parameters:

auto max(int a, int b) -> int;

This looks strange to a C++ developer at first. However, other languages like Swift, Rust, or Haskell use a similar notation. Thinking of auto as a func keyword might help.

Background

The main motivation for this alternative syntax is to specify the return type of a function template when the return type depends on the template arguments. Consider the following function:

template<typename A, typename B>
??? multiply(A a, B b) { return a*b; }

In this case, the general return type of multiply() is decltype(a*b). However, you can’t write this using the standard function syntax. C++ parses from left to right. Therefore, the function parameters a and b are not yet in scope when specifying the return type before the function name.

There is a workaround using declval(), but this gets confusing:

template<typename A, typename B>
decltype(std::declval<A&>() * std::declval<B&>())
multiply(A a, B b) { return a*b; }

The alternative syntax solves this problem. Now you can directly write the correct return type:

template<typename A, typename B>
auto multiply(A a, B b) -> decltype(a*b) { return a*b; }

Pros

With two different ways to specify the return type the question comes up which one to use. Let’s have a look at the pros first.

Consistency

I think consistency is a strong argument for the new syntax. The example above shows that the new syntax is helpful in certain cases. Lambda functions use trailing return types as well:

auto square = [] (int n) -> int { return n*n; }

The new syntax is aligned with the general trend of modern C++ to move towards a left to right syntax:

auto message = std::string{"Hello"};
using table = std::map<std::string, int>;
auto square = [] (int n) -> int { return n*n; }

Herb Sutter goes into more detail in his Almost Always Auto Style article.

Understanding

When reading a function declaration the main thing I’m interested in is understanding what it does. Assuming that functions are properly named by their developers, the most important information is in the function name and not the return type. Therefore, it makes sense to put the name first.

A trailing return type is also closer to mathematical notation and the way we speak about functions in math. Let $f\;\colon\;\mathbb{R} \to \mathbb{R}$ be a function…

Readability

Using trailing return types neatly aligns the function names:

auto is_empty() -> bool;
auto number_of_vertices()() -> int;
auto vertices_begin() -> VertexIterator;

The notation can be shorter than the standard return type, for example when returning a type defined inside a class such as VertexIterator above. The standard syntax would require the class scope to be specified explicitly:

SurfaceMesh::VertexIterator SurfaceMesh::vertices_begin() { ... }

The new syntax is slightly more concise:

auto SurfcaceMesh::vertices_begin() -> VertexIterator { ... }

Cons

Two main drawbacks come to mind.

Lack of Familiarity

Obviously, most existing code does not use the new syntax. Therefore, not all developers are familiar with it. There’s also a pitfall with override, which has to go after the return type since override is not part of the function type:

virtual auto foo() -> int override;

I’ve seen the new syntax being used in some open source libraries. However, they are clearly in the minority. Using the new syntax therefore would make your library inconsistent with large parts of the C++ ecosystem.

More Typing

Using the new syntax can require more typing, notably for trivial functions. I don’t think that many folks would prefer writing

auto func() -> void;

instead of

void func();

Excluding such cases would kill the consistency argument from above.

Conclusion

I’m not sure if using trailing return types everywhere is a good idea. The consistency argument and potential improvements in readability and understanding almost got me sold. They’re only nice to have though, and not much more.

The lack of familiarity is a major reason not to use the new syntax. Furthermore, C++14 introduced the possibility to automatically deduce the return type. With that, the multiply() example from above gets even simpler:

template<typename A, typename B>
auto multiply(A a, B b) { return a*b; }

This reduces the number of cases where the new return syntax is required, thereby making it a rather odd choice for normal function declarations.

Keep in mind though that auto return type deduction is not always what you want. It’s certainly fine for short functions like the example above. In general, however, I prefer explicit return types so that users know what they get without reading and understanding the full implementation or relying on an IDE.

Unit Testing: Short and Sweet

2022-01-21T00:00:00+00:00

This is the short and sweet introduction to unit testing I always wanted to have as a reference for colleagues, friends, and family. Enjoy.

What Is a Unit Test?

A unit test ensures that an individual unit of code behaves as intended. A unit is a minimal chunk of code that can be tested in isolation, such as a function or a class.

A test is not a unit test if it talks to a database, requires network access, writes to the filesystem, or requires a complex environment to be setup. This is crucial to keep things independent, robust, and fast.

Unit tests form the basis of the test automation pyramid. Write lots of them. Make them run fast.

Why Unit Testing?

Correctness: Unit testing helps you to write correct code. You detect errors early during development and avoid costly changes later on.
Evolution: Unit tests allow you to evolve your code over time. You can refactor your code without fear of introducing subtle bugs. This is key for reducing technical debt and improving your design.
Design: Unit testing encourages good design practices such as modularization and minimizing dependencies between components.
Documentation: Unit tests document the behavior of the code. They serve as a form of executable specification.

Unit Testing Best Practices

Good unit tests follow FIRST principles:

Fast: Run fast so that developers can run them frequently
Independent: Run standalone, in any order, without dependencies
Repeatable: Give consistent and reliable results on each run
Self-validating: Indicate success or failure without manual inspection
Timely: Written together with production code to foster testable design

Clean unit tests follow the AAA pattern:

Arrange: Setup the test
Act: Execute the function under test
Assert: Use an appropriate assert

This pattern implies testing a single concept per test case, using a single assertion.

Start with testing the happy path: Make sure that intended usage of the code produces the desired result.

Don’t forget the unhappy paths: Gracefully handle corner cases, unexpected input, pre-condition violations, or error conditions.

Aim to cover your complete public API with unit tests. Trivial functions like getters and setters might be excluded.

Use code coverage tools to analyze which code paths are actually triggered by your tests.

Let your testing code follow the same high standards as your production code: well designed, thoughtfully partitioned, and using meaningful names. Comments explain what is tested and why.

Refactor common setup code into a fixture to avoid repetition.

If your tests use tolerances, make them configurable so that you can check that nothing changed in the results.

Getting Started

Next time you…

add new code, write at least one unit test covering the happy path
find a bug, write a unit test that would have caught it
refactor a part of your code, bring it under test first

When time and circumstances permit: Setup code coverage and bring all critical parts of your code under test.

The Bottom Line

Unit testing is like exercising: you know it’s good for you, but it can be tough to get started. It’s even more difficult to stick to it after the initial enthusiasm wears off. It’s an investment in the future of your code that pays off.

One Week of Ray Tracing in Rust

2022-01-16T00:00:00+00:00

I started this year with one week of learning Rust and implementing a ray tracer from scratch using test-driven development.

My primary goal was to learn more about Rust. I had a look at the language before, but I did not yet find the time to work on any substantial project.

Writing a ray tracer from scratch is an ideal project for learning a new language. The task itself is straightforward, but you can go arbitrarily deep and sophisticated. Plus, working on something that gives instant visual results is always a pleasure.

The Ray Tracer Challenge

I followed the book The Ray Tracer Challenge by Jamis Buck, a test-driven guide to ray tracing. The book is written in an approachable style and does not assume any previous knowledge. As long as you have basic knowledge in any programming language you should be able to follow the text without problems.

The book is unique in the sense that it follows a test-driven approach independent of a particular programming language. Tests are described in easy to understand Gherkin language. Here’s an example:

Scenario: The magnitude of a normalized vector
  Given v ← vector(1, 2, 3)
  When norm ← normalize(v)
  Then magnitude(norm) = 1

It’s up to you to either implement the corresponding unit tests or to hook up the Gherkin files as test cases. I chose to write unit tests myself for sake of simplicity (at the expense of tedious repetition).

I admit: Learning a new language and following a test-driven approach slowed me down somewhat in the beginning. However, once I figured out the basics, things went smoothly. By the end of the week, I was comfortable enough to do much of the work without looking up things all the time.

Rust Experience

My experience working with Rust was consistently positive. This applies to both the language and the ecosystem around it. Rust prides itself for being a performant, reliable, and productive language. And Rust delivers.

If you have a C++ background like me, you’ll find that learning the basics is not that difficult. You’ll likely find the build system, package management, and IDE integration to be an absolute blessing. Having a minimal unit testing framework readily available was great for a quick start. Personally, I found generic programming in Rust to be much more enjoyable than in C++.

I won’t go down the rabbit hole of writing a comprehensive comparison between Rust and C++. You can find enough of them online. Instead, I’ll briefly list the pros and cons that I came across during this week.

The Good

Memory-safe and thread-safe by default
Immutable by default: Only allow change when necessary
Strict by default: No implicit type conversions
Concise yet expressive syntax: Sometimes Rust feels like a wild mix of C++ and Haskell, but in a positive sense.
Trailing function return types: Feels much more natural and closer to mathematical notation.
Traits system and generic programming: Helpful error messages!
Error reporting: The Result<T,E> type is cleaner than normal error codes and much simpler than exceptions.
Cargo package management and build system
IDE integration with VS Code and rust-analyzer
Static analysis with clippy
Straightforward parallelization with rayon

The Annoying

Working with strings. Although everything is consistent if you know the rationale behind, it is more cumbersome than in other languages
Having to type dots for floating point numbers (0. instead of 0) is a pain. At least in the beginning. Now it’s in muscle memory.
No operator() to overload. Therefore, no conventional matrix notation A(i,j) for element access.
No default constructors, cumbersome struct initializers
No function overloading
No default arguments
No variable argument lists
Const generics: As a recent addition to the language, this feature is incomplete.

Summing Up

Learning Rust and working with the language was a breeze of fresh air. Writing a ray tracer from scratch is a great programming exercise, and the book by Jamis Buck provides a low-barrier entry. The test-driven approach is well thought out and encourages using TDD in practice. I haven’t finished all the chapters yet, but I’m sure I’ll continue.

Likewise, I’ll deepen my knowledge about Rust. I was skeptical at first because of all the hype. However, the more I work with the language the more I enjoy it.

I encourage you to try Rust yourself. Stop reading blog posts about Rust! Head over to the Rust homepage, learn the basics, and use the language for a side project.

Keep an open mind.

Exceptions vs. Error Codes

2022-01-02T00:00:00+00:00

Consistent error handling is a key feature of a high quality software library. Until recently, the mesh processing library I’m working on did a poor job in this regard. This gave me the opportunity to revisit C++ error handling. I took a few notes in between. Hope this helps you choosing an error handling strategy in your C++ projects.

There are two major approaches to error handling in C++:

Error codes
Exceptions

I’ll briefly introduce both approaches and highlight their pros and cons.

Error Codes

The traditional way to report errors is by using error codes¹. They come in various forms, such as returning a simple bool or int value:

bool foo() { return true; }
int bar() { return 667; }

This basic form of error reporting relies on convention: What does it mean to return 667? Something good or bad? That’s up for interpretation and documentation. The error code does not convey any meaning by itself.

More well-engineered error reporting uses an enum or similar to provide symbolic constants that convey meaning about what type of error occurred:

enum ReturnType { SUCCESS = 1, SOLVE_FAILED = 2, BAD_INPUT = 3};

A major drawback of error codes is that they lead to function calls being intertwined with if..else blocks testing for the various error conditions.

int ret = func();
if (ret == SUCCESS) {
    printf("yay!");
}
else if (ret == SOLVE_FAILED) {
    printf("nay!");
}
else if (ret == BAD_INPUT) {
    printf("meh!");
}

The result is that program logic is mixed up with error handling. This is not a big issue in the simple example above, but it quickly becomes confusing in real-world code.

Exceptions

Exceptions are a more modern alternative to error codes. An exception is an error generated at runtime which is propagated through the call stack until it is either caught or the program terminates. Here’s a simple example:

#include <stdexcept>
#include <iostream>

void foo() {
    throw std::runtime_error("error!");
}

void bar() {
    foo();
}

int main() {
    try {
        bar();
    }
    catch (const std::runtime_error& e) {
        std::cerr << e.what() << std::endl;
    }
}

Pros

Here are the biggest advantages I see in using exceptions:

Cleaner code. Exceptions can be thrown at any point in the program, including class constructors which don’t return any value. Exceptions are independent of the return type of a function. The code catching the exception can be separate from the location the error occurred, thereby avoiding intertwining of application logic and error handling.

Proper types. Exceptions use proper types checked by the compiler. You can create your own exception classes to give the error additional semantic meaning and to pass information about the error with the exception. A practical example from mesh processing would be to include information about the location of the error so that you could highlight the problematic region in your visualization.

Harder to ignore. Function return values can be silently ignored. Exceptions need to be handled explicitly, otherwise the program will terminate. You are free to ignore an exception locally as long as it is taken care of higher up the call stack.

Standardization. You can’t avoid exceptions if you are using the standard library. The C++ Core Guidelines recommend the use of exceptions. Using exceptions is a modern C++ best practice.

Cons

Here are my top three drawbacks of exceptions:

Visibility. Exceptions are not directly visible in the source code. You can’t see what exceptions can be thrown by a function by looking at its signature. Even looking at the implementation does not reveal which exceptions could be thrown by other functions called in the code.

Control flow. Exceptions are an abrupt change in control flow, much like a goto statement. This can make it difficult to reason about the control flow of the program, making it harder to debug the code.

Implementation effort. Exceptions need special care when implementing them. Otherwise, you risk subtle errors such as memory leaks. Following the RAII² idiom is a key guideline here.

Conclusion

Personally, I like the simplicity of return codes. It’s a straightforward approach. You can teach it to a beginner in no time. This is not the case with exceptions. Doing exceptions right is a challenge. I’m not even sure I’m getting things right in PMP right now.

However, I feel that the advantages outweigh the disadvantages. If you are developing a library that adheres to modern C++ best practices, exceptions are the method of choice for error handling³.

References and Further Reading

Check out the following references if you are interested in more concrete guidelines on writing exception-safe code:

Exception-Safe Coding in C++ by Jon Kalb
How to: Design for exception safety by Microsoft
Modern C++ best practices for exceptions and error handling by Microsoft
Do you (really) write exception safe code? on StackOverflow
ISO C++ FAQ on Exceptions
Standard-Library Exception Safety by Bjarne Stroustrup

I use the term ‘error codes’ instead of ‘return codes’ because the codes could be reported differently than through a function return value, for example via a global error status variable. ↩
RAII stands for “resource acquisition is initialization” and means that resources are acquired during object initialization and released during object destruction. See the Wikipedia article for more information. ↩
There are a few exceptions, though (no pun intended). Special purpose code like hard real-time systems might have different constraints that prohibit the use of exceptions. ↩

Using clang-tidy with CMake

2021-12-21T00:00:00+00:00

Clang-tidy is a C++ static analysis tool from the LLVM project that is particularly helpful when modernizing your code base or when checking your code for compliance with established guidelines and best practices.

Typically, you need to run clang-tidy with the same options and compiler flags you use for compilation. Doing this manually can be quite a hassle.

One way to help with this is to use a compilation database. However, I always found this to be rather complicated by itself.

Luckily, if you are using CMake, there is a simpler alternative: You can directly use clang-tidy from CMake.

You need to do two steps:

Find and setup the clang-tidy command
Tell CMake to use clang-tidy

For the first step, you only need to use CMake’s find_program() and set the corresponding CMake variable to the command and options you want to use:

find_program(CLANG_TIDY_EXE NAMES "clang-tidy")
set(CLANG_TIDY_COMMAND "${CLANG_TIDY_EXE}" "-checks=-*,modernize-*")

In the above, I disable all default checks (-*) and only enable checks that advocate the use of modern C++ language constructs (modernize-*).

For the second step, you tell CMake to use clang-tidy by setting the CXX_CLANG_TIDY property for your build target:

set_target_properties(target PROPERTIES CXX_CLANG_TIDY "${CLANG_TIDY_COMMAND}")

That’s all! Run your build as usual and clang-tidy will report suggestions for modernization as warnings.

Here’s a fully self-contained CMakeLists.txt file for demonstration purposes:

cmake_minimum_required(VERSION 3.6)
project(clang-tidy-example)

# generate hello world file
file(
  GENERATE
  OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/hello.cpp
  CONTENT
    "#include <iostream>\n int main() { std::cout << \"Hello World\" << std::endl; exit(0); }"
)

# search for clang-tidy
find_program(CLANG_TIDY_EXE NAMES "clang-tidy" REQUIRED)

# setup clang-tidy command from executable + options
set(CLANG_TIDY_COMMAND "${CLANG_TIDY_EXE}" "-checks=-*,modernize-*")

# add target using generated source file
add_executable(hello ${CMAKE_CURRENT_BINARY_DIR}/hello.cpp)

# set CXX_CLANG_TIDY property after defining the target
set_target_properties(hello PROPERTIES CXX_CLANG_TIDY "${CLANG_TIDY_COMMAND}")

Run this with the usual cmake build steps:

mkdir build && cd build && cmake .. && make

And you’ll see something like this:

hello.cpp:2:6: warning: use a trailing return type for this function [modernize-use-trailing-return-type]
 int main() { std::cout << "Hello World" << std::endl; exit(0); }
 ~~~ ^
 auto           -> int

I’ll leave it up to you to decide whether the advice of clang-tidy makes sense in this particular case. Read this article to learn more about C++ trailing return types.

Hope this helps.

SGP 2021 Virtual Field Trip Report

2021-08-25T00:00:00+00:00

I attended this year’s Symposium on Geometry Processing (SGP), one of the premier conferences for publishing cutting-edge research in geometry processing. Here is my brief resume.

The conference was scheduled to take place in Toronto, Canada. However, due to current circumstances, the conference was virtual only. In any case, the organizers did an awesome job organizing a top notch conference and making it a highly worthwhile experience.

Positive side-effect of the virtual conference: All the graduate school lectures, technical papers, and keynotes are available online. Check out the program, there’s a whole bunch of interesting lectures and presentations. The graduate school lectures from previous years are archived online as well.

Graduate School Highlights

The graduate school is one of the most valuable aspects of SGP. It enables practitioners to stay up to date with the state of the art and to expand their knowledge in concentrated manner.

I particularly enjoyed the following lectures:

Maps Between Surfaces by Marcel Campen and Patrick Schmidt. Awesome presentation, great content, very instructive. I learned a lot from it, especially since this is a somewhat more recent area of research.
Shape Approximation and Applications by Tamy Boubekeur. A great overview on shape approximation techniques, including a classification of different methods and their development over time, as well as some recent research highlights. Well done and entertaining presentation definitely worth watching.
Digital Geometry by David Coeurjolly and Jacques-Oliver Lachaud. Geometry processing on voxel representations! Since I’m dealing a lot with voxel-based modeling in my day job, this was of particular interest to me.

Paper Highlights

The main part of the conference were three packed days of technical paper presentations. Quite a marathon! Zoom fatigue kicked in from time to time, but I kept on watching (almost) all presentations.

Best Paper Awards

There were plenty of interesting papers, most notably those winning this year’s best paper awards:

Surface Map Homology Inference
Geodesic Distance Computation via Virtual Source Propagation
Simulated Jet Engine Bracket Dataset

Papers of Interest

Beyond the above, there were a couple of papers I found very interesting. Without particular order:

Delaunay Meshing and Repairing of Defect-laden NURBS Models
Globally Injective Geometry Optimization with Non-Injective Steps
Simpler Quad Layouts using Relaxed Singularities
The Diamond Laplace for Polygonal and Polyhedral Meshes
Frame Field Operators
On Landmark Distances in Polygons

Test of Time Award

This is a new type of award to recognize papers that have stood the test of time, i.e., papers which are widely recognized throughout the community even after more than ten years. Great idea to highlight research that really sticks and has a long-lasting impact.

This first iteration of the award went to Poisson Surface Reconstruction. That’s certainly a well deserved recognition. The method and the corresponding software has become the de-facto standard for surface reconstruction.

Keynotes

We had three keynote speakers, each offering their unique insights:

Bradley Rothenberg, CEO, nTopology: “Engineering-driven design: a new foundation”
Geoffrey Hinton, University of Toronto/Google Research: “How to represent part-whole hierarchies in a neural net”
Lining Yao, Carnegie Mellon University: “Computing Morphing Matter: the Marriage of Geometry and Hidden Forces”

See the full descriptions for details.

Enjoy the show!

Awesome Doxygen Style

2021-07-07T00:00:00+00:00

Doxygen is the de-facto standard tool for C++ API documentation. It comes with a whole bunch of useful features such as auto-generated API documentation from annotated sources or automatic cross-references.

Unfortunately, the default Doxygen HTML output is quite dated, both in terms of visual style as well as navigation. Here’s an example:

Especially on mobile devices the resulting pages are notoriously difficult to navigate¹.

Customized HTML

Since I was not really satisfied with the above, I did some work to customize the output for our mesh processing library to have a slightly more modern look and feel. The results looked like this:

While this is arguably better than the default, it is far away from perfect.

doxygen-awesome-css

I recently came across a project that takes Doxygen customization even further: the doxygen-awesome-css project developed by @jothepro.

Some of the advantages are

a modern look and feel
simple integration and customization
improved mobile usability
dark mode support

I immediately adopted it for PMP. Here’s a snapshot:

Personally, I think this is indeed an awesome improvement.

Summary

If you are looking for a more modern style for your Doxygen docs, just give doxygen-awesome-css a try. Installation is super easy, you basically only need to include the additional CSS files into your repository and tell Doxygen to use them through the HTML_EXTRA_STYLESHEET option.

Check out the project website for more details. Hope this helps.

One might argue that mobile is not so important for API documentation. Fair enough. However, Doxygen can also used to build complete project websites including landing pages, tutorials, or high-level documentation. Therefore, accessibility on mobile is still an important aspect. ↩

Digital Gardens. Seriously?

2021-05-30T00:00:00+00:00

Some ideas take time to flourish. Maybe digital gardens are one of those ideas. Is it just a hyped revival of the personal website or is there more to it?

What Are Digital Gardens?

A digital garden is a digital space to cultivate your thoughts, ideas, notes, and knowledge. Think of personal wikis and experimental knowledge bases. Digital gardens are curated and evolve over time, sometimes growing wildly and sometimes getting pruned.

Digital gardens are less focused on publishing highly polished results but more about the process of developing ideas, thoughts, and knowledge over time. Less personal branding and search engine optimization but more personal growth and development instead.

Digital gardens are typically public so that others can learn from your current knowledge and understanding and provide feedback at an early stage. They are a prime example of working and learning in public.

What Are the Origins?

Digital gardens are clearly reminiscent of the quirky personal websites of the early web. Early roots of digital gardens can be traced back to Mark Bernstein’s 1998 essay Hypertext Gardens. Of course personal websites continue to exist today (hello https://neocities.org/), but they got largely superseded by blogs and social media, as Amy Hoy argues in How the Blog Broke the Internet.

In 2015, Mike Caulfield refined the metaphor of a garden further in his article The Garden and the Stream. In his analogy, the stream is the short-lived linear content like your blog or social media time-line whereas the garden is for content of a more durable nature with more complex relations in between. He traces the original idea of a garden back to Vannevar Bush’s 1945 (!) visionary essay As We May Think (read it, it’s a total blast).

The idea of a digital garden recently gained more and more traction. Two frequently cited examples are John Critchlow’s Of Digital Streams, Campfires and Gardens and Joel Hook’s My blog is a digital garden, not a blog. Maggie Appleton’s A Brief History & Ethos of the Digital Garden provides a more in-depth introduction for those who are curious to learn more.

Are They Any Good?

In short: yes, absolutely! I think it’s an idea worth exploring.

It’s amazing that more and more people think about alternatives to the one-size-fits-all streamlined silos of InstaTwitBook. Digital gardens stimulate the idea to create personalized content that is built to last and independent of locked-down third-party platforms. The IndieWeb community deserves a mention here as well.

One of the most interesting aspects is the idea of non-performative writing, thinking, and learning in public. This allows you to get your ideas out there early and refine them over time. It lowers the friction to start writing, and reduces the fear of being judged. We are all learners. Anyone having the courage to share his knowledge with the rest of the world deserves respect.

Of course, there’s a flip side to that approach as well, and that’s false information. The raw material inevitably contains factual errors. This can, however, be mitigated to some extent by indicating the maturity and reliability of the content. Maggie Appleton keeps up the gardening metaphor and categorizes her content as seedling (rough ideas), budding (somewhat cleaned up), or evergreen (fairly mature). Sounds like a fine solution to me. After all, it’s up to you to always question the reliability of information you find online.

Just a Hype?

Closing the loop to my initial question: Is it just a hype or re-branding of the good old personal website?

Yes. And No.

Digital gardens clearly continue the tradition of personal websites, wikis, and knowledge bases.

But then, there’s more to it.

The metaphor itself already fosters a different way of thinking. The aspect of working and learning in public adds a whole new dimension. Longevity, continuous growth and evolution are key characteristics. The connections and relations between different pieces of information get a completely new significance.

And then there’s technical evolution.

People are constantly exploring new tools to better support this style of working. Especially bi-directional linking between pages seems to emerge as a key technology. Interactive visualizations enable completely novel ways to explore these relations. And then there is the question how to bridge the boundaries of individual gardens.

Get Your Hands Dirty?

Now, should you grow a digital garden?

I can only offer my perspective: I’ve been tinkering with different approaches to capture personal knowledge for quite some time. The simple linear nature of a blog never really cut it for me. Therefore, I integrated a simple workflow to capture notes and ideas directly into my website. It’s based on Jekyll and plain Markdown and serves me quite well. You might call this a digital garden, it’s just not a public one for the moment.

Maybe it’s time to rethink a few things.

References and Further Reading

The Garden and the Stream: A Technopastoral by Mike Caulfield
Of Digital Streams, Campfires and Gardens by Tom Critchlow
Building a Digital Garden by Tom Critchlow
My blog is a digital garden, not a blog by Joel Hook
How the Blog Broke the Internet by Amy Hoy
A Brief History & Ethos of the Digital Garden by Maggie Appleton
Digital Garden Terms of Service by Shawn Wang
Learn In Public by Shawn Wang
As We May Think by Vannevar Bush
DigitalGardens on reddit
Digital Gardening on GitHub

A Minimalist Jekyll Style Guide

2021-05-26T00:00:00+00:00

You cannot get a simple system by adding simplicity to a complex system. - Richard O’Keefe

This is a style guide for clean and lean Jekyll websites. Its primary goal is to foster simplicity, performance, and maintainability. The contained guidelines are highly opinionated, totally biased, and somewhat radical. Nevertheless, I hope you’ll find some useful bits and pieces.

No External Dependencies

Don’t depend on external services or content delivery networks (CDNs). Bundle all resources locally so that you can still build, develop, and use your website while being offline.

Benefits:

performance
offline use
data privacy
version control

No CSS Frameworks

Modern CSS Grid Layout and Flexbox are powerful enough to create highly usable and responsive layouts with a few lines of code. No need to rely on heavy frameworks such as Bootstrap.

Benefits:

simplicity
performance

No JavaScript

A website as simple as mine does not really need JavaScript. Yours maybe neither. Less code to maintain, less to transfer over the wire. In addition, the site remains accessible for users with JavaScript disabled.

Benefits:

simplicity
performance
accessibility

Exception: MathJax for typesetting math. Only include it when you need it, see this post for details. I’m not happy with this exception, but I don’t see an alternative for the moment.

No Tracking

I had to remind myself why I’m writing this blog at all: First and foremost, I write for myself. For the pleasure of writing, to keep notes and to structure thoughts. If any of this turns out to be useful for others, great, glad I could help. No need to spy on my visitors.

Benefits:

data privacy
performance
peace of mind

No Comments

Let’s face it: Static site generators are simply not made for this. Sure, there are workarounds, I used to use one myself, but they are hackish at best and typically rely on some external service. Feedback via e-mail is fully sufficient.

Benefits:

simplicity
maintainability

RSS over E-Mail Subscription

Provide an RSS feed to allow users to get notified of new posts. Let your website be part of a better web that doesn’t constantly ask for e-mail addresses or personal information.

Benefits:

data privacy

No Favicons

I simply refuse to give in to the craziness today’s favicons. This used to be a single, simple, small image file added to your website. Nowadays, you are supposed to generate half a dozen images at different resolutions and formats plus some obscure, non-standard XML and text files. In addition, you need to include half a dozen <link> and <meta> tags in your HTML header to make those work. Heck, you need an external service to generate all this cruft for you. Just stop it.

Benefits:

simplicity
maintainability
peace of mind

No Pre-Built Theme

Jekyll themes are great to get you started, but most of them come with a lot of boilerplate code. Ironically, some of the most bloated ones carry the word “minimal” in their name. It’s in the nature of a theme to provide a highly generic solution. Instead, build your own site from scratch. Only include what you need and understand.

Benefits:

performance
simplicity
maintainability
learning

Hint: set theme: null in your _config.yml to avoid generating default CSS styles.

No Web Fonts

This is the hardest part for me. I’m a confessing typophile, and I just adore a beautiful and well-crafted typeface. I used to waste a lot of time switching back and forth between different fonts and tweaking their settings. Enough of that. The performance impact is non-negligible, and so is the implementation and maintenance burden. Therefore, I finally settled with a simple system font stack.

Benefits:

performance
simplicity
productivity

Plain Markdown

Use plain Markdown whenever possible. No inline HTML or Liquid language in blog posts. This ensures your content can easily be converted to another format if needed. Use a linting tool to check your Markdown files.

Benefits:

maintainability

Minimal Liquid Code

Keep Liquid code to a bare minimum. It’s tempting to add more and more features with a few lines of code, but it only gets harder to maintain over time.

Benefits:

simplicity
maintainability

Minimal Plugins

I use GitHub Pages, so I’m restricted to the officially supported plugins. I keep it down to a few essential ones:

jekyll-feed
jekyll-seo-tag
jekyll-sitemap
jekyll-redirect-from

No Syntax Highlighting

Sounds crazy, but in fact many syntax highlighting color schemes are more than sub-optimal in terms of accessibility. Think of bad contrast ratios and color-blindness. Choose whatever you like in your IDE, but I’ll keep it plain and simple on my site. Bonus points: No superfluous CSS required. No excessive DOM size due to the huge amount of <span> elements being generated by the Jekyll default syntax highlighter.

Benefits:

accessibility
performance
simplicity

Hint: Disable syntax highlighting in your _config.yml:

kramdown:
  syntax_highlighter_opts:
    disable: true

No Responsive Images

Generating and serving responsive images is sort of a science on its own. You eventually end up generating a dozen files in different resolutions, versions, and file formats. This is certainly doable using additional plugins, custom Liquid code, or external web services. However, none of those approaches is simple and all of them violate some other guideline above. Therefore, I stick to simple compressed and optimized JPEG images for the moment.

Benefits:

simplicity

No Embedded Videos

Embedding videos from external sources is convenient but comes with a cost: Lots of JavaScript and CSS gets pulled from an external domain. In addition, this approach can be problematic in terms of data privacy (cookies, tracking). Also requires inline HTML or custom Liquid as well as additional CSS for embedding. For now, I just use a good old link with an optional image.

Benefits:

performance
data privacy

Closing Remarks

Obviously, these guidelines are not for everyone and not for every situation. That being said, I still hope I got you thinking about wether all the bells and whistles on your website are really worth it.

Finally, I’m curious how long it’ll take before I break one of the rules. Subscribe via RSS and check the next post for fancy web fonts. ;-)

In the meantime, here’s some food for thought:

Generating Primitive Shapes in C++

2021-05-03T00:00:00+00:00

This is the last part of my brief series on procedural mesh generation of simple shapes in C++. The two previous articles covered generating Platonic solids and different types of spheres. I recommend reading the other articles first, especially if you want to try out the code yourself.

This part covers the following primitives:

Plane
Cone
Cylinder
Torus

As with the previous articles, the code is in C++, using the PMP library, and written with a focus on simplicity. I only expose a minimal set of options and don’t really optimize for performance. However, you can easily extend the code to control additional properties such as position, size, and orientation.

The Plane

Let’s start with the simplest shape, the plane. In the most trivial case, this is just single quad with four vertices lying in the plane:

SurfaceMesh plane()
{
    SurfaceMesh mesh;

    // add vertices in x-y plane
    auto v0 = mesh.add_vertex(Point(0,0,0));
    auto v1 = mesh.add_vertex(Point(0,1,0));
    auto v2 = mesh.add_vertex(Point(1,1,0));
    auto v3 = mesh.add_vertex(Point(1,0,0));

    // add face
    mesh.add_quad(v0,v1,v2,v3);

    return mesh;
}

While the above is fine for basic applications, you typically want to be able to refine the mesh into smaller elements, such as shown in the sequence below.

Generating such a regular grid isn’t that much more complicated. All you need is two nested for loops to generate vertices and faces. For the sake of simplicity, I fix the resolution to be the same in each direction.

SurfaceMesh plane(size_t resolution)
{
  SurfaceMesh mesh;

  // generate vertices
  Point p(0, 0, 0);
  for (size_t i = 0; i < resolution + 1; i++) {
    for (size_t j = 0; j < resolution + 1; j++) {
      mesh.add_vertex(p);
      p[1] += 1.0 / resolution;
    }
    p[1] = 0;
    p[0] += 1.0 / resolution;
  }

  // generate faces
  for (size_t i = 0; i < resolution; i++) {
    for (size_t j = 0; j < resolution; j++) {
      auto v0 = Vertex(j + i * (resolution + 1));
      auto v1 = Vertex(v0.idx() + resolution + 1);
      auto v2 = Vertex(v0.idx() + resolution + 2);
      auto v3 = Vertex(v0.idx() + 1);
      mesh.add_quad(v0, v1, v2, v3);
    }
  }

  return mesh;
}

If you’re curious to experiment with the code, go ahead and de-couple the resolution for the different plane directions, or add options for position, size, and orientation.

The Cone

Next, let’s have a look at a slightly more complex shape, the cone. A cone basically consists of a circular base connected to a single tip or apex.

The coarsest approximation to a cone is a tetrahedron (the leftmost image above), which you already saw in the tutorial about Platonic solids.

The code for generating a cone follows the same pattern that you are familiar with by now: Generate vertices first and then connect the faces.

For generating vertices, I sample a circle in the x-y plane, controlled by parameters for resolution and radius. I offset the tip vertex in z direction by height and add it last.

Adding faces is as simple as connecting two consecutive vertices from the base circle to the tip vertex. Finally, I add a single polygonal face to close the bottom of the cone.

SurfaceMesh cone(size_t resolution,
                 Scalar radius,
                 Scalar height)
{
  SurfaceMesh mesh;

  // add vertices subdividing a circle
  std::vector<Vertex> base_vertices;
  for (size_t i = 0; i < resolution; i++) {
    Scalar ratio = static_cast<Scalar>(i) / (resolution);
    Scalar r = ratio * (M_PI * 2.0);
    Scalar x = std::cos(r) * radius;
    Scalar y = std::sin(r) * radius;
    auto v = mesh.add_vertex(Point(x, y, 0.0));
    base_vertices.push_back(v);
  }

  // add the tip of the cone
  auto v0 = mesh.add_vertex(Point(0.0, 0.0, height));

  // generate triangular faces
  for (size_t i = 0; i < resolution; i++) {
    auto ii = (i + 1) % resolution;
    mesh.add_triangle(v0, Vertex(i), Vertex(ii));
  }

  // reverse order for consistent face orientation
  std::reverse(base_vertices.begin(), base_vertices.end());

  // add polygonal base face
  mesh.add_face(base_vertices);

  return mesh;
}

The Cylinder

Next, let’s have a look at cylinders which are barely more complicated than cones. To be more precise, I consider discrete approximations to a cylinder which are prisms, i.e., n-sided polygonal base faces parallel to each other connected by n other quadrilateral faces joining the two base faces.

Generating a cylinder is very similar to generating a cone as described above. The major difference is that I sample two different base circles and generate quadrilateral faces connecting pairs of vertices from those two circles.

SurfaceMesh cylinder(size_t resolution,
                     Scalar radius,
                     Scalar height)
{
  SurfaceMesh mesh;

  // generate vertices
  std::vector<Vertex> bottom_vertices;
  std::vector<Vertex> top_vertices;
  for (size_t i = 0; i < resolution; i++) {
    Scalar ratio = static_cast<Scalar>(i) / (resolution);
    Scalar r = ratio * (M_PI * 2.0);
    Scalar x = std::cos(r) * radius;
    Scalar y = std::sin(r) * radius;
    Vertex v = mesh.add_vertex(Point(x, y, 0.0));
    bottom_vertices.push_back(v);
    v = mesh.add_vertex(Point(x, y, height));
    top_vertices.push_back(v);
  }

  // add faces around the cylinder
  for (size_t i = 0; i < resolution; i++) {
    auto ii = i * 2;
    auto jj = (ii + 2) % (resolution * 2);
    auto kk = (ii + 3) % (resolution * 2);
    auto ll = ii + 1;
    mesh.add_quad(Vertex(ii), Vertex(jj), Vertex(kk), Vertex(ll));
  }

  // add top polygon
  mesh.add_face(top_vertices);

  // reverse order for consistent face orientation
  std::reverse(bottom_vertices.begin(), bottom_vertices.end());

  // add bottom polygon
  mesh.add_face(bottom_vertices);

  return mesh;
}

The Torus

The final shape I’ll describe in this tutorial is the well-known torus or doughnut shape. A torus is generated by revolving a circle in three-dimensional space about an axis that is coplanar with a circle.

The code pattern remains the same: Vertex generation comes first, then add the corresponding faces. The indexing of the faces gets a bit more tricky due to the nested for loops, but that’s basically about it. I use some intermediate variables to make the code clearer, hope this helps.

SurfaceMesh torus(size_t radial_resolution,
                  size_t tubular_resolution,
                  Scalar radius,
                  Scalar thickness)
{
  SurfaceMesh mesh;

  // generate vertices
  for (size_t i = 0; i < radial_resolution; i++) {
    for (size_t j = 0; j < tubular_resolution; j++) {
      Scalar u = (Scalar)j / tubular_resolution * M_PI * 2.0;
      Scalar v = (Scalar)i / radial_resolution * M_PI * 2.0;
      Scalar x = (radius + thickness * std::cos(v)) * std::cos(u);
      Scalar y = (radius + thickness * std::cos(v)) * std::sin(u);
      Scalar z = thickness * std::sin(v);
      mesh.add_vertex(Point(x, y, z));
    }
  }

  // add quad faces
  for (size_t i = 0; i < radial_resolution; i++) {
    auto i_next = (i + 1) % radial_resolution;
    for (size_t j = 0; j < tubular_resolution; j++) {
      auto j_next = (j + 1) % tubular_resolution;
      auto i0 = i * tubular_resolution + j;
      auto i1 = i * tubular_resolution + j_next;
      auto i2 = i_next * tubular_resolution + j_next;
      auto i3 = i_next * tubular_resolution + j;
      mesh.add_quad(Vertex(i0), Vertex(i1), Vertex(i2), Vertex(i3));
    }
  }

  return mesh;
}

Closing Remarks

This finishes my brief series on procedural mesh generation of simple shapes. Together with part I and part II this should provide you with a solid basis for creating simple shapes in a modeling application or to test an algorithm against shapes with known properties.

The complete code is available as well. In order to try it out, just copy the file to src/MyViewer.cpp in the PMP project template, build the project, and run the ./myviewer executable.

Comments or questions? Simply drop me a mail.

Check for Broken Links in Jekyll

2021-03-28T00:00:00+00:00

You know the frustrating experience: There you are, reading an interesting article, you click on that promising link… and all you get is a 404 page.

If you are lucky, that is.

Let’s try to do better than that. Fixing dead links will not only delight your esteemed readers but also make search engine crawlers happy. Here’s a simple way to check for broken links in your Jekyll-based website.

The html-proofer Ruby gem is a tool to check the validity of your HTML output. Among other things, it checks for broken links, both internal and external.

Installation is quick and easy:

Add gem "html-proofer" to your Gemfile
Run bundle install

Run the tool on your Jekyll build directory:

bundle exec htmlproofer --assume_extension '.html' ./_site

The --assume_extension option automatically adds extensions to file paths, as this is used by extension-less URLs in Jekyll 3 and GitHub pages.

See the HTMLProofer README for more details and options. In my case, I added the --http_status_ignore=999 option to filter some external links returning that particular error when not using a regular browser.

You can use the Ruby-based task automation tool Rake to further automate the process. Add gem "rake" to your Gemfile and run bundle install again to install it. Then create a Rakefile with the following contents:

require 'html-proofer'

task :test do
  sh "bundle exec jekyll build"
  options = { :assume_extension => '.html' }
  HTMLProofer.check_directory('_site/', options).run
end

Now you can simply run bundle exec rake test to check your HTML files.

Depending on your setup, you could also integrate this into your build pipeline to run the test automatically, e.g., when you push new changes or regularly during a nightly build.

Generating Meshes of a Sphere

2021-03-27T00:00:00+00:00

Spheres are one of the most basic geometric shapes we can think of. However, there are a variety of methods for generating surface meshes of a sphere. In this brief tutorial, I will describe four of them:

UV sphere
Icosphere
Quad sphere
Goldberg polyhedra

This article is a follow-up on my previous tutorial on generating Platonic solids. I recommend reading it first since I will re-use parts of the code from that article. The code is in C++ and using the PMP library. Use the PMP project template for ease of implementation and visualization.

The UV Sphere

The UV sphere is a standard shape available in many 3D modeling tools such as Blender. The basic approach is to tessellate the sphere along meridians and parallels, i.e., lines from one pole to another and lines parallel to the equator. The resulting mesh contains a fan of triangles around the poles and quadrilateral elements everywhere else.

The code below is rather straightforward. I first add all vertices and then add the corresponding triangular and quadrilateral faces. Note that I intentionally did not optimize the code in any way for the purpose of this article.

SurfaceMesh uv_sphere(int n_slices, int n_stacks)
{
  SurfaceMesh mesh;

  // add top vertex
  auto v0 = mesh.add_vertex(Point(0, 1, 0));

  // generate vertices per stack / slice
  for (int i = 0; i < n_stacks - 1; i++)
  {
    auto phi = M_PI * double(i + 1) / double(n_stacks);
    for (int j = 0; j < n_slices; j++)
    {
      auto theta = 2.0 * M_PI * double(j) / double(n_slices);
      auto x = std::sin(phi) * std::cos(theta);
      auto y = std::cos(phi);
      auto z = std::sin(phi) * std::sin(theta);
      mesh.add_vertex(Point(x, y, z));
    }
  }

  // add bottom vertex
  auto v1 = mesh.add_vertex(Point(0, -1, 0));

  // add top / bottom triangles
  for (int i = 0; i < n_slices; ++i)
  {
    auto i0 = i + 1;
    auto i1 = (i + 1) % n_slices + 1;
    mesh.add_triangle(v0, Vertex(i1), Vertex(i0));
    i0 = i + n_slices * (n_stacks - 2) + 1;
    i1 = (i + 1) % n_slices + n_slices * (n_stacks - 2) + 1;
    mesh.add_triangle(v1, Vertex(i0), Vertex(i1));
  }

  // add quads per stack / slice
  for (int j = 0; j < n_stacks - 2; j++)
  {
    auto j0 = j * n_slices + 1;
    auto j1 = (j + 1) * n_slices + 1;
    for (int i = 0; i < n_slices; i++)
    {
      auto i0 = j0 + i;
      auto i1 = j0 + (i + 1) % n_slices;
      auto i2 = j1 + (i + 1) % n_slices;
      auto i3 = j1 + i;
      mesh.add_quad(Vertex(i0), Vertex(i1),
                    Vertex(i2), Vertex(i3));
    }
  }
  return mesh;
}

The Icosphere

An alternative to the classic UV sphere is the icosphere. The core idea here is to iteratively subdivide an icosahedron. In contrast to the UV sphere, the resulting mesh is a pure triangle mesh and has a much more regular vertex distribution and element size.

Generating an icosphere basically requires three steps:

Generate an initial icosahedron
Subdivide the triangles
Project the vertices to the sphere

I already covered steps #1 and #3 in my previous article. We can directly re-use the icosahedron() and project_to_unit_sphere() functions.

The only missing piece is a way to subdivide the triangles of the initial icosahedron. In this implementation, I’m using the Loop subdivision function available in PMP. See the reference docs and the Wikipedia article for details.

The resulting code is straightforward:

SurfaceMesh icosphere(size_t n_subdivisions)
{
  auto mesh = icosahedron();
  SurfaceSubdivision subdivision(mesh);
  for (size_t i = 0; i < n_subdivisions; i++)
  {
    subdivision.loop();
    project_to_unit_sphere(mesh);
  }
  return mesh;
}

Bonus task: Try implementing the Loop subdivision step yourself! The algorithm is rather straightforward and provides a excellent opportunity to exercise your skills to work with meshes. If you get stuck, you can always check the implementation provided in PMP.

The Quad Sphere

The quad sphere is another standard shape available in many 3D modeling tools. The algorithm to generate a quad sphere iteratively subdivides an initial hexahedron. As the name implies, the resulting mesh is a pure quad mesh.

The code is quite similar to the icosphere() function above: I start by generating a hexahedron and then use a subdivision function to refine the mesh. As before, I project the points back to the unit sphere during each iteration to get a nicely regularized shape.

SurfaceMesh quad_sphere(size_t n_subdivisions)
{
  auto mesh = hexahedron();
  SurfaceSubdivision subdivision(mesh);
  for (size_t i = 0; i < n_subdivisions; i++)
  {
    subdivision.catmull_clark();
    project_to_unit_sphere(mesh);
  }
  return mesh;
}

I already introduced the hexahedron() and project_to_unit_sphere() functions before. However, since I’m dealing with a quad mesh here, I need something different for the subdivision step. The algorithm of choice is Catmull-Clark subdivision, a very well known technique in computer graphics. See the PMP reference docs and the Wikipedia article for more information.

Goldberg Polyhedra

You can generate yet another type of sphere mesh simply by re-using another function already introduced in the previous article. The dual() function computes the dual polyhedron of a mesh. Applying this function to the icosphere meshes yields polygonal meshes as shown above, also known as Goldberg polyhedra. The resulting meshes contain only hexagonal and pentagonal faces.

Wrapping Up

That’s all for today. I said it would be a brief article, and so it is. Hope this was useful anyway. The full code is available to experiment with as well.

Generating Platonic Solids in C++

2021-01-03T00:00:00+00:00

This is a short tutorial on generating polygonal surface meshes of the five Platonic solids in C++. You can learn a few basics of working with meshes along the way. I’m using the Polygon Mesh Processing Library for implementation. The code is straightforward, so you can easily adapt it to another data structure or programming language.

Motivation

My primary motivation for this article is very simple:

You want to generate a mesh of a Platonic solid
Here is some straightforward C++ code to do so

Now why exactly would this be interesting? Well, having the possibility to generate a mesh with known properties is useful in many situations. Here are three examples:

Generating example data for an algorithm you are developing
Generating shapes in your application without shipping meshes
Unit testing geometric algorithms

Generating simple shapes also is a canonical example for doing your first steps using a mesh library, a sort of “Hello, mesh!”. If you are new to working with meshes, this is a great starting point to get familiar with the basics.

Bootstrapping

I’m using the Polygon Mesh Processing Library (PMP) as mesh data structure in this tutorial. However, any modern mesh data structure providing basic functions such as adding vertices and polygonal faces should be sufficient for this tutorial. Skip this section if you’re using another data structure.

If you want to quickly visualize the resulting meshes, I recommend downloading and compiling the PMP project template, which contains a ready-to-use mesh viewer. Just clone the repository:

git clone --recursive https://github.com/pmp-library/pmp-template.git

Build the project:

cd pmp-template && mkdir build && cd build && cmake .. && make

Run the viewer:

./myviewer

During this tutorial, I’ll define a few functions to generate the different shapes. It’s easiest to add those functions to the MyViewer class and call them on a keyboard shortcut. Here’s how to do this:

Find the MyViewer::keyboard() function in your favorite IDE
Add a new case label such as GLFW_KEY_G to the switch statement
Add the function you want to call
Add a call to update_mesh() to update the viewer
Re-compile and run ./myviewer

That’s all you need to get started, so let’s go!

The Five Platonic Solids

The Platonic solids are a set of well-known convex polyhedra with particular properties, e.g., all faces are of the same type, the faces are regular (all angles and sides are the same), and the same number of faces are incident to each vertex. In 3D space, there are only five polyhedra satisfying these criteria: The tetrahedron, hexahedron, octahedron, dodecahedron, and the icosahedron. Here they are, from left to right:

The Platonic solids date back to the time of the ancient Greeks, if not earlier. They played a key role in Plato’s philosophy, hence the name. If you are interested, see the Wikipedia article for more information.

The Tetrahedron

Let’s begin with the simplest Platonic solid, the tetrahedron. Four vertices and four triangular faces, that’s all. Here’s the code:

SurfaceMesh tetrahedron()
{
  SurfaceMesh mesh;

  // choose coordinates on the unit sphere
  float a = 1.0f / 3.0f;
  float b = sqrt(8.0f / 9.0f);
  float c = sqrt(2.0f / 9.0f);
  float d = sqrt(2.0f / 3.0f);

  // add the 4 vertices
  auto v0 = mesh.add_vertex(Point(0, 0, 1));
  auto v1 = mesh.add_vertex(Point(-c, d, -a));
  auto v2 = mesh.add_vertex(Point(-c, -d, -a));
  auto v3 = mesh.add_vertex(Point(b, 0, -a));

  // add the 4 faces
  mesh.add_triangle(v0, v1, v2);
  mesh.add_triangle(v0, v2, v3);
  mesh.add_triangle(v0, v3, v1);
  mesh.add_triangle(v3, v2, v1);

  return mesh;
}

The Hexahedron

The code for the hexahedron isn’t that much more complicated. You just have to add a few more points and faces: Eight vertices, six quadrilateral faces:

SurfaceMesh hexahedron()
{
  SurfaceMesh mesh;

  // choose coordinates on the unit sphere
  float a = 1.0f / sqrt(3.0f);

  // add the 8 vertices
  auto v0 = mesh.add_vertex(Point(-a, -a, -a));
  auto v1 = mesh.add_vertex(Point(a, -a, -a));
  auto v2 = mesh.add_vertex(Point(a, a, -a));
  auto v3 = mesh.add_vertex(Point(-a, a, -a));
  auto v4 = mesh.add_vertex(Point(-a, -a, a));
  auto v5 = mesh.add_vertex(Point(a, -a, a));
  auto v6 = mesh.add_vertex(Point(a, a, a));
  auto v7 = mesh.add_vertex(Point(-a, a, a));

  // add the 6 faces
  mesh.add_quad(v3, v2, v1, v0);
  mesh.add_quad(v2, v6, v5, v1);
  mesh.add_quad(v5, v6, v7, v4);
  mesh.add_quad(v0, v4, v7, v3);
  mesh.add_quad(v3, v7, v6, v2);
  mesh.add_quad(v1, v5, v4, v0);

  return mesh;
}

The next shape in the series is the octahedron. You could do exactly the same as above and manually specify all vertex coordinates and face indices. However, this becomes tedious rather quickly.

Instead, you can do something slightly more intelligent and exploit the fact that every convex polyhedron has a dual polyhedron.

Interlude: Computing the Dual Polyhedron

The dual polyhedron is a bit like a twin—or maybe it is more like Dr. Jekyll and Mr. Hyde? I’ll leave it up to you. Here’s the slightly more formal definition: For each convex polyhedron, there is a dual polyhedron with a face for each vertex and a vertex for each face of the original polyhedron. Here’s an illustration of the concept of duality:

The original mesh is a triangle mesh of a sphere, edges shown in dark gray. The edges of the dual mesh are highlighted in teal. Each vertex of the dual mesh corresponds to a face in the original mesh; each vertex of the original mesh corresponds to a polygonal face in the dual mesh. Note that computing the dual also is a practical way to convert a triangle mesh into an general polygon mesh. Here is how you can compute the dual:

void dual(SurfaceMesh& mesh)
{
  // the new dual mesh
  SurfaceMesh tmp;

  // a property to remember new vertices per face
  auto fvertex = mesh.add_face_property<Vertex>("f:vertex");

  // for each face add the centroid to the dual mesh
  for (auto f : mesh.faces())
    fvertex[f] = tmp.add_vertex(centroid(mesh, f));

  // add new face for each vertex
  for (auto v : mesh.vertices()) {
    std::vector<Vertex> vertices;
    for (auto f : mesh.faces(v))
      vertices.push_back(fvertex[f]);

    tmp.add_face(vertices);
  }

  // swap old and new meshes, don't copy properties
  mesh.assign(tmp);
}

Admittedly, this code is a little more specific to the PMP library. I’m using the centroid() function to compute the center of a face. Here’s the definition:

Point centroid(const SurfaceMesh& mesh, Face f)
{
  Point c(0, 0, 0);
  Scalar n(0);
  for (auto v : mesh.vertices(f)) {
    c += mesh.position(v);
    ++n;
  }
  c /= n;
  return c;
}

I am also using the built-in property mechanism to attach data to mesh entities (mesh.add_face_property...). Here, I’m storing and retrieving the vertices added to the dual mesh. If you want to keep it simple, you can also use a std::vector for managing this information.

I’m also using two frequently used operations when working with meshes:

I’m using iterators to go through all mesh entities (faces, vertices)
I’m using a circulator to traverse all faces incident to a vertex.

The circulator is in the for (auto f : mesh.faces(v)) part. If you are using a different data structure, you need to figure out how to do this for yourself. Check the API documentation of your library. Or just switch to PMP!

The Octahedron

With the new function to compute the dual mesh in place, we have all it takes to generate another Platonic solid. The octahedron is the dual polyhedron of the hexahedron, which we can already generate using the hexahedron() function. All that’s left is to combine the two:

SurfaceMesh octahedron()
{
  auto mesh = hexahedron();
  dual(mesh);
  return mesh;
}

Now that’s a function to my liking: Create something, do something, and return the result. As simple and clear as it gets. Comparing the original hexahedron and the dual octahedron shows that there is an issue, though: The dual mesh is much smaller and inside the original hexahedron.

Normalizing Positions on the Unit Sphere

For the functions defined so far, I took care to compute the vertex coordinates in such a way that they are on the unit sphere. It would be nice to have the same property for the dual meshes as well. A simple solution is to project the vertices of the dual mesh back to the unit sphere. Here’s a function for doing exactly that:

void project_to_unit_sphere(SurfaceMesh& mesh)
{
  for (auto v : mesh.vertices()) {
    auto p = mesh.position(v);
    auto n = norm(p);
    mesh.position(v) = (1.0 / n) * p;
  }
}

Now let’s use this in our function generating the octahedron:

SurfaceMesh octahedron()
{
  auto mesh = hexahedron();
  dual(mesh);
  project_to_unit_sphere(mesh);
  return mesh;
}

And this is what the result looks like:

Much better. The two shapes have all their points nicely aligned on the unit sphere, just as we want them to be.

Icosahedron and Dodecahedron

Finally, let’s tackle the remaining two polyhedra, icosahedron and dodecahedron. The two are dual to another, so we only need to generate one of them by hand and then compute the other one using the dual() function. I’m choosing the icosahedron for the manual implementation:

SurfaceMesh icosahedron()
{
  SurfaceMesh mesh;

  float phi = (1.0f + sqrt(5.0f)) * 0.5f; // golden ratio
  float a = 1.0f;
  float b = 1.0f / phi;

  // add vertices
  auto v1  = mesh.add_vertex(Point(0, b, -a));
  auto v2  = mesh.add_vertex(Point(b, a, 0));
  auto v3  = mesh.add_vertex(Point(-b, a, 0));
  auto v4  = mesh.add_vertex(Point(0, b, a));
  auto v5  = mesh.add_vertex(Point(0, -b, a));
  auto v6  = mesh.add_vertex(Point(-a, 0, b));
  auto v7  = mesh.add_vertex(Point(0, -b, -a));
  auto v8  = mesh.add_vertex(Point(a, 0, -b));
  auto v9  = mesh.add_vertex(Point(a, 0, b));
  auto v10 = mesh.add_vertex(Point(-a, 0, -b));
  auto v11 = mesh.add_vertex(Point(b, -a, 0));
  auto v12 = mesh.add_vertex(Point(-b, -a, 0));

  project_to_unit_sphere(mesh);

  // add triangles
  mesh.add_triangle(v3, v2, v1);
  mesh.add_triangle(v2, v3, v4);
  mesh.add_triangle(v6, v5, v4);
  mesh.add_triangle(v5, v9, v4);
  mesh.add_triangle(v8, v7, v1);
  mesh.add_triangle(v7, v10, v1);
  mesh.add_triangle(v12, v11, v5);
  mesh.add_triangle(v11, v12, v7);
  mesh.add_triangle(v10, v6, v3);
  mesh.add_triangle(v6, v10, v12);
  mesh.add_triangle(v9, v8, v2);
  mesh.add_triangle(v8, v9, v11);
  mesh.add_triangle(v3, v6, v4);
  mesh.add_triangle(v9, v2, v4);
  mesh.add_triangle(v10, v3, v1);
  mesh.add_triangle(v2, v8, v1);
  mesh.add_triangle(v12, v10, v7);
  mesh.add_triangle(v8, v11, v7);
  mesh.add_triangle(v6, v12, v5);
  mesh.add_triangle(v11, v9, v5);

  return mesh;
}

Computing the dodecahedron now is straightforward:

SurfaceMesh dodecahedron()
{
  auto mesh = icosahedron();
  dual(mesh);
  project_to_unit_sphere(mesh);
  return mesh;
}

And here is the result showing both the icosahedron and dodecahedron enclosed by the unit sphere:

Wrapping Up

Alright, that’s it for the moment. I hope this was useful to you. The full code is available as well. I’ll eventually write more articles like this one, so stay tuned.

In the meantime, tell me what you think. Comments? Questions? Suggestions? Drop me a mail.

Thanks to u/lycium on Reddit for suggesting a simplification of the icosahedron() function.

Graphics and Geometry Resources

2020-12-30T00:00:00+00:00

Now here’s a positive consequence of 2020: There are plenty of awesome resources on graphics and geometry available online for everyone to watch, enjoy, and educate oneself. Here’s my current watch list.

Toronto Geometry Colloquium

This is a regular online seminar presenting varying topics from geometry processing and related disciplines such as computational fabrication, graphics, or 3D deep learning. The format is innovative: A 10 minute short presentation shows recent work and a longer 50 minute session provides a more in-depth presentation.

The talks are broadcast live on YouTube. Recordings are available on their YouTube channel as well. Checkout their website for more information.

Technion Seminar

The Technion Center for Graphics and Geometric Computing organizes an international seminar on geometric modeling, geometry processing, and computational geometry. The format is a more traditional one hour talk. ~~Checkout their website for the program, schedule, and abstracts.~~

Symposium on Geometry Processing 2020

This year’s SGP conference talks are still available on YouTube. Checkout the program and the conference website. All paper sessions and keynotes are available on the conference YouTube channel.

Eurographics 2020

Similarly, this year’s Eurographics conference has lots of material online: There is a YouTube channel with all the paper sessions and keynotes. The conference papers are also freely accessible from the digital library.

Ke-Sen Huang’s Graphics Resources

Finally, a page that is always worth sharing: Ke-Sen Huang’s resources for computer graphics contains a curated list of graphics conferences, including links to full-text papers, videos, supplemental material, code, project pages, etc. Probably one of the most valuable resources on graphics out there.

Do you have a great resource on graphics and geometry to share? I’d be glad to hear!

Jekyll Website Performance Improvement

2020-12-14T00:00:00+00:00

This article provides practical tips on how to optimize the loading speed of your website. Some advice specifically aims at users of Jekyll, the blog-enabled static site generator. However, the basic ideas also apply to other tools and should therefore be easy to transfer.

Note: This is an article written by and for the occasional web developer. If you’re a professional full-time web developer, you might know much of the content. I still encourage you to continue reading, though!

Why Care?

Why should you care about performance? We’ve got tiny supercomputers in our pockets, so who cares? And aren’t static websites such as those generated by Jekyll super fast out of the box? Well, not so fast.

Performance matters a lot, and tiny improvements can make a vast difference. According to research from Google, the speed it takes to load a page has an impact of around 75% for user experience, clearly above other criteria such as ease of use or attractiveness:

If you would like to learn more, have a look at this talk from Google’s 2019 I/O conference:

When it comes to static websites the situation surely is not as bad as in other cases. Remember Flash, anyone? However, investigating performance more closely reveals opportunities for optimization even for static sites.

Performance Analysis

First, we need to measure performance before we can optimize it. My current tool of choice is Google’s Lighthouse. You can either run it in a browser through Chrome Dev Tools or online at Google’s web.dev pages.

Lighthouse not only analyzes raw performance but also provides insight into how well your website performs according to

Accessibility
Best practices
Search engine optimization

Here’s what I got for an older version of my site using Chrome Dev Tools:

That’s quite a bit of red and orange. In contrast, this is what I get after optimization, using web.dev this time:

Read on to see how you might get there as well.

Minification

Low-hanging fruits first.

A straightforward way to reduce the size of your pages is to minify the HTML code. Just like other text-based formats, HTML can be minified by reducing white space, comments, newlines, or optional closing tags.

There is a Jekyll plugin that exactly does that job for you: jekyll-compress-html. The usage is super simple:

Download the compress.html file from the repository
Copy it to the _layouts folder of your Jekyll website
Edit your top-level layout file (usually default.html) to have the following front matter:
```
---
layout: compress
---
```

This will change your HTML code from something nicely formatted and human-readable to something much more compact. Here is a comparison before and after enabling minification:

This saves about 1K in size on a random HTML page of mine. Doesn’t sound too impressive, but Lighthouse already shows some improvement.

Only Include What You Need

From here on things get slightly more complicated, but the gain in speed is also significantly greater. Hang tight.

Depending on your Jekyll setup, you eventually include a lot of additional assets like CSS frameworks, JavaScript libraries, or custom fonts. Chances are that you only need a subset of them.

I use Bootstrap to build this site (see this post), which depends on jQuery. Both libraries are quite heavyweight. Turns out I only need a fraction of them, offering an excellent opportunity for size reduction.

Bootstrap

I compile my own version of Bootstrap using Sass, see this post for details. Therefore, I can easily configure which CSS modules to include from the Bootstrap distribution. Here is my top-level bootstrap.scss file with all unused modules commented out:

@import "functions";
@import "variables";
@import "mixins";
@import "root";
@import "reboot";
@import "type";
@import "images";
@import "code";
@import "grid";
@import "tables";
/* @import "forms"; */
/* @import "buttons"; */
@import "transitions";
/* @import "dropdown"; */
/* @import "button-group"; */
/* @import "input-group"; */
/* @import "custom-forms"; */
@import "nav";
@import "navbar";
/* @import "card"; */
/* @import "breadcrumb"; */
/* @import "pagination"; */
/* @import "badge"; */
/* @import "jumbotron"; */
/* @import "alert"; */
/* @import "progress"; */
/* @import "media"; */
/* @import "list-group"; */
/* @import "close"; */
/* @import "toasts"; */
/* @import "modal"; */
/* @import "tooltip"; */
/* @import "popover"; */
/* @import "carousel"; */
/* @import "spinners"; */
@import "utilities";
/* @import "print"; */

That’s more than half of the modules, and I’m sure I could optimize this even further after more careful investigation.

jQuery

The Bootstrap JavaScript code depends on jQuery, which is quite a heavy library providing a lot of functionality. The good news is: As long as you are only using the CSS part of Bootstrap, you are fine not to include it.

Check if you really need the Bootstrap JavaScript modules. If not, just remove the corresponding <script> tags for both from your template and watch your performance score improving.

In my case, I still use jQuery to retrieve comments on blog posts via GitHub, see this post for details. However, instead of including jQuery by default on all pages, I now only include it on blog posts using the comment functionality:

{% if page.issue and site.github_comments_repository %} ...
<script src="/js/jquery.min.js"></script>
... {% endif %}

I admit that it is still overkill include jQuery just to retrieve some data from GitHub. I’m sure there are more lightweight alternatives.

MathJax

Many technical blogs include support for MathJax, a convenient way to typeset mathematical formulas in your posts. Again, this is quite a heavy dependency pulling in lots of JavaScript code.

Similarly, the solution is to use conditional inclusion: Only include MathJax when you really need it. Here, a dedicated front-matter variable in posts needing MathJax support will do the trick:

---
title: Fancy Post With Lots of Math
mathjax: true
---

Next, change your layout or include file (depending on where you actually include MathJax) to check for the variable being defined:

{% if page.mathjax %}
<script type="text/x-mathjax-config">
  <!-- your config here -->
</script>
<script async src="/MathJax.js?config=TeX-AMS_HTML"></script>
{% endif %}

Note the async attribute above to enable asynchronous loading of the script. This eventually enhances performance in case you actually use MathJax.

Deferred Loading

As shown above, adding the async attribute to <script> tags is one way to improve page load time for scripts that you absolutely have to load. Using the defer attribute is another alternative. See the script HTML element documentation for more information.

Another commonly used technique is to defer the loading by placing your <script> tags at the very end of the document. However, you should not need this anymore when using the async or defer attributes.

For more information on how to eliminate render-blocking resources, please see the corresponding Google Developers page.

Inline Critical CSS

Another optimization technique is to inline CSS code directly into the HTML document instead of loading an external script. The key point is to inline only critical CSS styles needed to render the first paint and make the core functionality work.

I adopted a simple version of this by using an online critical path CSS generator. This takes your website URL and the full CSS code as input and generates a small set of critical CSS styles to include directly in your HTML header.

The resulting CSS looks far from being optimal, but for the moment it works fine. I am sure there are better alternatives out there. Maybe you know something that integrates well with Jekyll? Drop me a mail.

Asynchronous Loading of CSS

Another tweak I applied was to defer loading of the full CSS files using a ~~hack~~ creative solution based on the media attribute.

<link
  rel="stylesheet"
  href="style.css"
  media="print"
  onload="this.media='all'"
/>

Note that this requires inlining of critical CSS, otherwise you will get ugly “Flashes of Unstyled Content” (FOUC). See the full description at css-tricks.com for more details.

Fonts

Custom web fonts are popular and available to everyone through services like Google Fonts. However, ask yourself if you really need them.

As an alternative, consider using a system font stack relying on fonts already installed on the user’s system. This offers significant performance gains since

there are no font files to transfer and load
the browser likely has the fonts cached

All major operating systems include somewhat decent fonts these days, so this really is an alternative. Plus, the system fonts match the look and feel of the operating system, so users are used to it.

Here’s one way to use system fonts:

body {
  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica,
    Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";
}

However, if you are like me and want more precise control over the fonts being used, there are some guidelines to do this efficiently:

Host the fonts yourself if possible. This avoids additional connection requests and/or name resolution.
Use font-display: swap in the @font-face definition to make sure text remains visible while the browser loads the fonts.
Reduce the size of the font files by sub-setting. Only include the glyphs for the languages you are using.

Pre-load essential font files by adding appropriate special tags to your header:

<link
  rel="preload"
  href="/font.woff2"
  as="font"
  type="font/woff2"
  crossorigin
/>

Last remark: Popular icon font sets such as Font Awesome are quite heavy as well. The latter contains something around 1000 icons (depending on your version), and I doubt you really need all of them. Consider creating a customized version containing only the icons you actually use. However, this is a story for another day. Time to wrap up.

Summary

In this article, I showed a few basic techniques to optimize the performance of your website, with a particular focus on Jekyll users.

There are plenty of ways to optimize the speed of your website even further. Images are one area I didn’t cover. There is a lot to gain from using modern image formats and compression. You can also provide images in different pre-scaled resolutions so that the browser has less work to do.

However, these examples also show that optimization usually comes with a certain cost in terms of

implementation effort and
maintenance overhead.

Some techniques described here make maintenance and development much more cumbersome. The manual inlining of critical CSS is one such example. It requires manual updates whenever you change one of your critical styles. There are better solutions out there, but I did not yet investigate in detail.

Do you have further advice on performance optimization? Something easy and efficient based on Jekyll? Drop me a mail.

PMP Library at SGP

2020-12-03T00:00:00+00:00

Earlier this year, we were honored to be invited to give a presentation on our pmp-library at the SGP 2020 graduate school. Unfortunately, due to the special circumstances, the event was virtual only. The good thing is that a recording is available on YouTube:

All other videos from the SGP graduate school are available online as well.

Enjoy the show!

PMP Library Version 1.2.1 Released

2020-05-10T00:00:00+00:00

We just released a minor bug-fix release of the Polygon Mesh Processing Library, version 1.2.1. See the official release announcement as well as the full changelog for details.

Have fun!

Task Tracking and the Bullet Journal Method

2020-05-02T00:00:00+00:00

For the last decade or so I used Org mode for tracking tasks and taking notes. This worked reasonably well while I was mostly working full time on a single project. Nowadays, things are a bit more complicated. I usually have multiple projects going on both at work and in private. Over time, I ended up with a wild bunch of different .org files for different purposes floating around on different computers. As you can imagine, things got increasingly hard to track. Eventually, I almost stopped consistently tracking tasks due to the inadequacy of this system. It was clear that I needed a better solution.

Modern Note-Taking Apps: No Thanks

One solution would have been to adopt a modern cloud-based note-taking application such as Microsoft OneNote, Evernote, or similar. Unfortunately, these systems typically result in vendor lock-in due to proprietary storage formats. In addition, there are some serious concerns about data privacy and security. To me, all of the above simply does not sound quite right for something that is supposed to last and be accessible for years to come. Alternatives such as setting up my own system to keep all .org files in sync did not seem very appealing, either.

Bullet Journal to the Rescue

Roughly a year ago, I stumbled upon a different approach at handling tasks and notes: The Bullet Journal method originally introduced by Ryder Carroll. This simple technique is completely analog and does not require any sophisticated digital tools. All you need is this:

A notebook and a pen. That’s it. Plus a few simple guidelines how to organize your tasks and notes. The following gives you a glimpse of the method.

Bullet Journal Basics

The core of the method is something called rapid logging, which introduces a short-form notation for quickly adding different types of entries to your notebook. The basic entries are tasks, events, and notes:

Once you are finished with a task you simply mark it with a cross:

A dedicated index allows you to quickly look up entries later on. Specific logs gather tasks you need to accomplish in a certain time frame such as the current month. On top of that, collections help you organize your entries into related categories. Finally, migration is the process of moving incomplete tasks to a future log so that they remain visible. A migrated task gets an arrow to signify that it is taken care of somewhere else:

An important aspect of manual task migration is that it helps you to identify which tasks really matter to you. Before migrating a task, take a moment and think about whether it really is still relevant. If not, simply cross it out. If you already migrated a task several times, chances are high that it is not really that important or urgent. Or, you are just very good at procrastinating. In any case: Consider manual task migration as a chance for simplification. The effort it takes is an incentive to get things done and focus on the essential.

Got interested? Take a minute or two and checkout Ryder Carroll’s original introduction to the technique:

Wrapping Up

I quickly adopted this simple low-tech approach for pretty much everything I want to track: Tasks, notes, ideas, meeting minutes, important dates, habits, stuff to read, sketches, and whatever else comes to my mind.

After more than one year of intensive usage I’m still amazed by the system’s simplicity, flexibility, and effectiveness. Of course, there are some rough edges as well, especially when it comes to bridging the gap to other (online) systems. Overall, however, I’m pretty satisfied with the system and I don’t see myself switching to anything else anytime soon.¹

Want to know more? Checkout the official website and the updated video.

If you like what you see, just give it a try! I hope it will help you getting more organized and maybe even more focused on what really matters to you.

Ironically, I was using analog calendars before Org-mode. I guess it was the lack of flexibility of traditional calendars and the general lack of a system that made me switch to Org-mode in the first place. ↩

PMP Library Version 1.2 Released

2020-03-15T00:00:00+00:00

We just released a new minor release of the Polygon Mesh Processing Library, version 1.2. This release includes a couple new features, enhancements, bug fixes, and updates to third-party libraries. Highlights include:

Improved rendering of general polygons, avoiding erroneous tessellation into overlapping/flipped triangles in case of non-convex polygons.
Added support for rendering using matcaps.
Eigen interoperability: Matrix and vector classes can now be assigned and cast from Eigen matrices and vectors.
Matrix and vector classes can now be constructed using initializer lists.

See the official release announcement as well as the full changelog. for details.

Have fun!

PMP Library Version 1.1 Released

2019-05-30T00:00:00+00:00

We just released the new version 1.1 of the Polygon Mesh Processing Library. This release includes a couple new features, enhancements, bug fixes, and updates to third-party libraries. Highlights include:

An implementation of the hole filling algorithm by Liepa¹
An improved SurfaceSmoothing algorithm avoiding model shrinking²
A new compile-time switch to choose between float or double as default Scalar type
Native support for high-DPI displays on all supported operating systems and browsers

See the official release announcement as well as the full changelog. for details.

Have fun!

Peter Liepa. Filling holes in meshes. In Proceedings of Eurographics Symposium on Geometry Processing, pages 200–205, 2003. ↩
Misha Kazhdan, Justin Solomon, and Mirela Ben-Chen. Can mean‐curvature flow be modified to be non‐singular? Computer Graphics Forum, 31(5), 2012. ↩

Publication Pages Using Jekyll Collections

2019-03-03T00:00:00+00:00

Jekyll collections are a great way to group and process pages of related content. I’m currently using collections to build my publications page and associated project pages. This post provides a short rundown how to implement something like this.

Add a Collection

First of all, you need to add a collection to your Jekyll configuration file, _config.yml. In this case, I aptly name it publications:

collections:
  publications:
    output: true
    permalink: /:collection/:name

The output: true option configures Jekyll to write a rendered page for each document in the collection. This will be the project page associated to each publication. The permalink option configures the output path based on the base name of the document.

Create an Example Document

Next, create a directory named _publications to store one Markdown file for each publication. Each of these files will hold the publication meta-data such as title, authors, or where the work was published. In this example, I’m using the following dummy content and save it in a file named mypub19.md:

---
layout: default
title: A New Method for Fancy Research
authors: John Doe and Mary Jane
publication: Journal of Fancy Research
year: 2019
doi: http://dx.doi.org/XX.XXX/
---

Add a Publications Page

The next step is to create an overview page that lists all your publications. In my example, I simply call it publications.html and use some basic Liquid loop to list all publications in reverse chronological order:

---
layout: default
title: Publications
---

<h1 class="mt-4">Publications</h1>
{% assign publications = site.publications | sort: "year" | reverse %}
{% for pub in publications %}
<div class="pubitem">
  <div class="pubtitle">{{ pub.title }}</div>
  <div class="pubauthors">{{ pub.authors }}</div>
  <div class="pubinfo">{{ pub.publication }}, {{ pub.year}}</div>
</div>
{% endfor %}

Integrating this into my minimal jekyll-bootstrap-template will give you something like this:

Admittedly, this looks rather dull, so let’s add at least some minimal CSS styling:

.pubitem {
  margin: 2em 0;
  line-height: 1em;
}

.pubtitle {
  margin-bottom: 0.5em;
  line-height: 1.2em;
  font-weight: bold;
}

.pubauthors,
.pubinfo {
  font-size: 75%;
  margin-bottom: 0.75em;
}

This produces:

Adding Teaser Images

Next up, a proper publication entry needs a teaser image, isn’t it? By convention, I keep a small teaser image using a name based on

the base name of the publication file
plus a _small suffix
plus the file extension

The base name can be accessed in Liquid using the slug variable. Add the following code to the pubitem element, just before pubtitle element:

<div class="pubteaser">
  <a href="{{pub.url}}">
    <img
      src="/images/publication-pages/{{ pub.slug }}_small.jpg"
      alt="{{pub.slug}} publication teaser"
    />
  </a>
</div>

Add some CSS for it:

.pubteaser {
  clear: both;
}

.pubteaser a {
  float: left;
  margin-right: 2em;
}

.pubteaser img {
  width: 100px;
  border: 1px solid black;
}

The result already looks much closer to something acceptable:

Adding Links

In order to keep the overview page clear and concise, I only include two links per publication:

A download link for the PDF
A link to the project page providing more details

By convention, I keep a PDF file using the same base name as the publication file in my downloads folder. The following snippet adds the corresponding links to the overview page. Just add it at the end of the pubitem element:

<div class="publinks">
  <a href="/download/{{ pub.slug}}.pdf"><i class="far fa-file-pdf"></i> PDF</a
  >&nbsp;&nbsp;
  <a href="{{pub.url}}"><i class="fas fa-link"></i> Project Page</a>
</div>

Add some more CSS:

.publinks {
  font-size: 75%;
}

And the result looks like this:

Project Pages

Now, the final missing piece is a proper project page providing supplementary information and additional downloads. I’m controlling what this page looks like using a custom layout named publication. I’m providing a sample layout below, simply add it as publication.html to your _layouts directory and replace the default layout in your publication meta-data file with publication.

---
layout: default
---

<div class="page">
  <h1 class="mt-4 publication-title">{{ page.title }}</h1>
  <div class="publication-authors">{{ page.authors }}</div>
  <div class="publication-info">{{ page.publication }}, {{ page.year}}</div>
  <div class="publication-teaser">
    <img
      src="/images/publication-pages/{{ page.slug }}.jpg"
      alt="project teaser"
    />
  </div>
  {{ content }}
  <h2 id="downloads">Downloads</h2>
  <p>
    <a href="/download/{{ page.slug }}.pdf"
      ><i class="far fa-file-pdf"></i> PDF</a
    >&nbsp;&nbsp; {% if page.slides %}
    <a href="/download/{{ page.slug }}_slides.pdf"
      ><i class="far fa-file-pdf"></i> Slides</a
    >&nbsp;&nbsp; {% endif %}
    <a href="/download/{{ page.slug }}.bib"
      ><i class="far fa-file-alt"></i> BibTex</a
    >&nbsp;&nbsp; {% if page.doi %}
    <a href="{{ page.doi }}"><i class="fas fa-external-link-alt"></i> DOI</a
    >&nbsp;&nbsp; {% endif %}
  </p>
</div>

After adding some dummy abstract to the publication file this results in the following page:

The above layout assumes a two additional files to be present:

A full size teaser image named {{ page.slug }}.jpg
A BibTex file named {{ page.slug }}.bib

Presentation slides and DOI links are optional and only included if you specify the corresponding keys in the publication file preamble. Add additional links as needed, e.g., for downloading example code, data, or links to a repository.

Wrapping Up

That’s all there is to it. For your convenience, I set up a repository providing a complete minimal working example. You’ll probably want to modify and adjust this to your needs, but hopefully this will help to get you started.

PMP Library Version 1.0 Released

2019-02-18T00:00:00+00:00

After years of contemplation, vivid discussion, crazy experimentation, and lots of hard work, we finally released the first official version of the Polygon Mesh Processing Library. Highlights include:

A simple and efficient mesh data structure for storing and processing polygonal surface meshes
Canonical geometry processing algorithms such as simplification, remeshing, subdivision, smoothing, or curvature computation
Ready-to-use visualization tools to build your own mesh processing applications
Compilation into JavaScript to build browser-based apps (demo)

For more information visit pmp-library.org. See the changelog for a high-level summary of changes.

Get your own copy by cloning:

git clone --recursive https://github.com/pmp-library/pmp-library.git

Checkout the release tag:

cd pmp-library && git checkout 1.0.0

Configure and build:

mkdir build && cd build && cmake .. && make

Run the mesh processing app

./mpview ../external/pmp-data/off/bunny.off

If you encounter any glitches or problems please report the issue on our GitHub issue tracker.

Have fun!

SGP Summer School Presentations Online

2019-01-28T00:00:00+00:00

The Symposium on Geometry Processing (SGP) is one of the premier conferences for publishing cutting-edge research in—hold your breath—geometry processing.

The conference also hosts a pre-conference graduate school every year, during which well-known researchers in the field present their perspective on fundamentals and current research trends.

Starting from 2016, the organizers have recorded these presentations. They are now available online at

http://school.geometryprocessing.org/

for everyone to watch and enjoy. That’s a ton of great material. So, next time you can’t decide what to watch in the evening simply try one of these!

Ray Tracing Books Online for Free

2019-01-25T00:00:00+00:00

Two standard books on ray tracing are now available online for free:

Matt Pharr announced the availability of “Physically Based Rendering”
Eric Haines announced the availability of “An Introduction to Ray Tracing”

Even though personally I prefer reading such content on plain old paper, this is still great news for anyone interested in the subject. I can only congratulate the authors for taking this step.

In case of “Physically Based Rendering”, part of their motivation seems to be due to the low printing quality of the second printing of the third edition. I can only confirm this. I recently bought the 3rd edition and I was really disappointed by the lack of quality. Hopefully some publishers will learn a lesson or two from this, although I’m not too optimistic in this regard.

Unit Testing File I/O

2019-01-20T00:00:00+00:00

A somewhat tricky question when it comes to unit testing is how to test components involving file I/O. Recall that a good unit tests should run fast and independent of its execution environment. A test involving file I/O inevitably breaks these rules, which is why some people don’t even consider such a test a unit test.

Whatever your definition of a unit test is: There is a need for testing I/O components. Almost every moderately complex software system will involve some form of file I/O, e.g., for data exchange, serialization, or debugging. In other words: If you take software testing seriously, you’ll probably need to deal with testing I/O components at some point.

Testing Strategies

In the following, I’ll briefly outline some testing strategies that I’ve come across so far and highlight their strengths and weaknesses. The main use case I’ve got in mind is the Polygon Mesh Processing Library, in which we support numerous mesh file formats for reading and writing. Therefore, my selection of strategies might be a bit biased towards this use case.

Checksums

The basic idea is to check the output files (or input objects) for equality using previously computed checksums. This is probably one of the simplest tests to implement. It basically only requires some baseline data and a checksum function, and it will ensure correctness for known inputs or outputs. However, the simplicity comes at a cost. The resulting test will be highly fragile, i.e., the slightest change in the code or the input data requires a baseline update. This in turn can drastically slow down your development speed when using test-driven development.

Round-Trip

A slightly more advanced strategy is to do a round-trip: Generate some test data, write it to a file, read the contents back in, and make sure that the resulting object is (approximately) identical to the baseline. This approach is still rather simple and straightforward to implement. It also gives you much more flexibility in how strict you want your comparisons to be. However, it also requires code for both reading and writing a particular format, which might not always be feasible.

Formal Verification

An even more sophisticated approach would be to parse the file and verify that it conforms to a formal specification of the file format, e.g., by using a formal grammar. This strategy eventually results in a high level of correctness and comprehensive test coverage. At the same time, the implementation effort might be considerable. In case of missing or incomplete specifications it might be difficult if not impossible to realize.

Image-Based Comparisons

Sometimes, a picture is worth a thousand words. The same applies to a rendered image of your data. Similar to the checksum-based method mentioned above, you can use image-based comparisons to test for strict equality. In addition, this approach opens up the possibility to test within a certain tolerance. It can also help to spot visual artifacts that are not easily captured by a numeric characteristic. A main drawback of this strategy is that it requires a certain amount of infrastructure, i.e., to do off-screen rendering and to read and compare image data. However, it might come in handy for general testing as well, so it might be well worth the effort.

File System Independence

The strategies outlined above should give you some ideas how to write tests for components involving file I/O. However, they do not yet help with the dependence on the file system itself and the problems associated with this. Therefore, a major goal should be to break this dependence so that the unit test runs fast and independent of the execution environment.

One possible way to achieve this is to apply the Single Responsibility Principle (SRP), one of the SOLID principles of object-oriented software design. It basically states that every module or class should only be responsible for a single functionality.

Let’s consider a simplistic writer function as an example:

void write(const std::string& filename)
{
    // additional checks on filename omitted for brevity
    std::ofstream ofs(filename.c_str());
    ofs << "test" << std::endl;
    ofs.close();
}

int main(int argc, char** argv)
{
    write("/tmp/test.txt");
    return 0;
}

Usually, the write() function would take care of checking the file specified in filename for readability, open it, write the contents to disk, and finally close the file again. This means, however, that the function has more than one responsibility:

File handling and
Data conversion to the disk format

Whenever you can describe the responsibility of a class or function with an and, this should give you a hint that this part of the code eventually violates the SRP principle.

The obvious solution is to split the responsibility so that the file handling is not part of the write() function. Instead, it should only handle the conversion of the data to the desired file format.

In C++, we can achieve this rather easily by using the output stream class std::ostream. Using this interface allows for both output to an actual file using std::ofstream as well as output to a string buffer using std::ostringstream for unit testing.

The write() function simply would become:

void write(std::ostream& ofs)
{
    ofs << "test" << std::endl;
}

The regular invocation would pass an already opened std::ofstream:

int main(int argc, char** argv)
{
    std::ofstream ofs("/tmp/test.txt");
    write(ofs);
    ofs.close();
    return 0;
}

In contrast, the unit test invocation would pass an instance of std::ostringstream and then validate the resulting contents of the string stream for correctness:

int main(int argc, char** argv)
{
    std::ostringstream ofs;
    write(ofs);
    if (ofs.str() != "test\n")
        std::cerr << "test failed" << std::endl;
    return 0;
}

Of course, the above is only a totally simplistic and fictitious example, but it should be sufficient to get the idea of separating responsibilities across so that you can make your tests independent of the file system.

For a real-world application you’d probably add some intermediate class to handle the actual file system interactions such as checking for existence, permissions, opening, and closing. You could then test this abstraction layer even further by using mock objects. For now, however, that’s way out of scope for this post.

Wrapping Up

In this post, I outlined basic strategies for unit testing software components involving file I/O as well as a concrete way to refactor your I/O functions to have clearer responsibilities and to be less dependent on the underlying file system.

My current strategy of choice for validating I/O results is to do a round trip of export and re-import. It’s not perfect, that’s for sure, but it offers a good compromise between correctness, completeness, flexibility, and implementation effort.

In case you are aware of any additional testing strategies for file I/O, I’d be glad to hear!

References and Further Reading

Creating a Jekyll Bootstrap Template

2019-01-12T00:00:00+00:00

I recently rewrote this site to use a custom Jekyll theme based on Bootstrap and Sass. I kept some notes during the process, and now I reworked them into this short guide on building a bare-bones Jekyll Bootstrap template.

The following assumes you’re already somewhat familiar with Jekyll. If this is not the case, I’d recommend to head over to the Jekyll homepage first in order to learn some basics.

For the impatient: The complete code is available on GitHub. However, I’m sure you’ll get more out of this if you follow along and try the steps for yourself.

Creating the Skeleton

We begin by creating a fresh Jekyll skeleton:

jekyll new jekyll-bootstrap-minimal --blank

Next, add a directory to contain the Bootstrap Sass distribution:

cd jekyll-bootstrap-minimal
mkdir -p css/bootstrap

Get the latest version of Bootstrap from their website. Be sure to download the source distribution. Unzip the downloaded file and copy the scss directory into the skeleton:

cp -r ~/Downloads/bootstrap-4.2.1/scss/* css/bootstrap/

Create the main Sass file css/style.scss and import Bootstrap:

---
---

/* modify Bootstrap variables here */

@import "bootstrap/bootstrap";

/* add additional CSS rules below */

Create a default _config.yml file telling Jekyll where to search for Sass files:

sass:
  sass_dir: css
  style: compressed

I added the compression option so that the resulting .css files are smaller and load faster.

The last thing to do is to import the jQuery and Bootstrap JavaScript libraries:

mkdir js
wget https://code.jquery.com/jquery-3.3.1.min.js -P js
cp ~/Downloads/bootstrap-4.2.1/dist/js/* js/

That’s all there is for the absolute minimum. However, this will not yet give you any useful site template. The following section describes how to add a default layout in order to get a minimal site up and running.

Adding a Minimal Layout

Create a default layout file as _layouts/default.html:

<!DOCTYPE html>
<html lang="en">
  {% include header.html %}
  <body>
    {% include navbar.html %}
    <div class="container">{{ content }}</div>
    {% include footer.html %}
    <script src="/js/jquery-3.3.1.min.js"></script>
    <script src="/js/bootstrap.min.js"></script>
  </body>
</html>

Create the _includes directory:

mkdir _includes

For the content of the include files I borrow bits and pieces from the Portfolio Item template made by Start Bootstrap.

Start with the header in _includes/header.html:

<head>
  <link href="http://gmpg.org/xfn/11" rel="profile" />
  <meta http-equiv="X-UA-Compatible" content="IE=edge" />
  <meta http-equiv="content-type" content="text/html; charset=utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />

  <title>{{ page.title }} - {{ site.title }}</title>

  <link rel="stylesheet" href="/css/style.css" />
</head>

Add a navbar in _includes/navbar.html:

<nav class="navbar navbar-expand-lg navbar-dark bg-dark">
  <div class="container">
    <a class="navbar-brand" href="#">{{ site.title }}</a>
    <button
      class="navbar-toggler"
      type="button"
      data-toggle="collapse"
      data-target="#navbarResponsive"
      aria-controls="navbarResponsive"
      aria-expanded="false"
      aria-label="Toggle navigation"
    >
      <span class="navbar-toggler-icon"></span>
    </button>
    <div class="collapse navbar-collapse" id="navbarResponsive">
      <ul class="navbar-nav ml-auto">
        <li class="nav-item active">
          <a class="nav-link" href="#"
            >Home
            <span class="sr-only">(current)</span>
          </a>
        </li>
        <li class="nav-item">
          <a class="nav-link" href="#">About</a>
        </li>
        <li class="nav-item">
          <a class="nav-link" href="#">Services</a>
        </li>
        <li class="nav-item">
          <a class="nav-link" href="#">Contact</a>
        </li>
      </ul>
    </div>
  </div>
</nav>

Add the footer to _includes/footer.html:

<footer class="py-2 bg-dark">
  <div class="container">
    <p class="m-0 text-center text-white">
      Copyright &copy; {{ site.time | date: '%Y' }}
    </p>
  </div>
</footer>

Now it’s time to add some content to your index.html file:

---
layout: default
title: Home
---

<h1 class="my-4">
  Page Heading
  <small>Secondary Text</small>
</h1>

<div class="row">
  <div class="col-md-8">
    <img class="img-fluid" src="http://placehold.it/750x500" alt="" />
  </div>
  <div class="col-md-4">
    <h3 class="my-3">Project Description</h3>
    <p>
      Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam viverra
      euismod odio, gravida pellentesque urna varius vitae. Sed dui lorem,
      adipiscing in adipiscing et, interdum nec metus. Mauris ultricies, justo
      eu convallis placerat, felis enim.
    </p>
    <h3 class="my-3">Project Details</h3>
    <ul>
      <li>Lorem Ipsum</li>
      <li>Dolor Sit Amet</li>
      <li>Consectetur</li>
      <li>Adipiscing Elit</li>
    </ul>
  </div>
</div>

<h3 class="my-4">Related Projects</h3>

<div class="row">
  <div class="col-md-3 col-sm-6 mb-4">
    <a href="#">
      <img class="img-fluid" src="http://placehold.it/500x300" alt="" />
    </a>
  </div>
  <div class="col-md-3 col-sm-6 mb-4">
    <a href="#">
      <img class="img-fluid" src="http://placehold.it/500x300" alt="" />
    </a>
  </div>
  <div class="col-md-3 col-sm-6 mb-4">
    <a href="#">
      <img class="img-fluid" src="http://placehold.it/500x300" alt="" />
    </a>
  </div>
  <div class="col-md-3 col-sm-6 mb-4">
    <a href="#">
      <img class="img-fluid" src="http://placehold.it/500x300" alt="" />
    </a>
  </div>
</div>

We used the site.title Liquid variable in the above includes. Therefore, we need to add it to _config.yml:

title: Jekyll Bootstrap
sass:
  sass_dir: css
  style: compressed

That’s it. Kick off Jekyll to build and serve your site:

jekyll serve

The result should look like this:

Not too bad, ain’t it? In any case, the resulting template should provide you with a good starting point for building whatever website you have in mind. Checkout the repository for the full source code and feel free to fork and modify to suit your needs. Hope this helps!

On Software Testing in Research

2019-01-05T00:00:00+00:00

Extensive software testing is not a wide-spread practice in academic research. In this short argumentative post, I’ll outline some of the negative consequences this entails. In the end, I hope to convince you that testing is not only something for industrial software development but that it is also essential for doing research using software prototypes.

From Bugs to False Results

People with an academic background often have no or little exposure to the practice of software testing. This is unfortunate, because if you want to make sure your software behaves correctly there is practically no way around comprehensive software testing.

While recent developments such as the Graphics Replicability Stamp Initiative are a step in the right direction, I’m convinced that this is not yet sufficient. Assuring the reproducibility of the results simply means reproducibility of the bugs. And I’m sure there are plenty of them out there, especially considering how a typical research prototype usually comes into existence, i.e., written in a rush to meet the next paper deadline.

Of course, there’s also the possibility you’re a rock star developer, and your software never contains a bug. But what about your collaborators? Your students? The third-party libraries you’re depending on? The industry average defect rate is around 1–25 bugs per 1000 lines of code¹. And that’s industry average and not research average. Do the math.

The consequence of those undiscovered bugs are scientific publications including false results. Nobody really needs that.

Validate Hypotheses on a Solid Basis

You might argue that testing is a waste of time when writing throw-away research prototypes. I think this is wrong. You write your prototype for obtaining results, that’s for sure. More importantly, however, the prototype is your central tool for validating—or falsifying—your hypotheses. This is at the very core of the scientific method. If you do not relentlessly test your prototype, the results you obtain can be completely misleading. Eventually, you assume your hypothesis is correct while it’s not. Or, you might discard your hypothesis because your results are unsatisfactory. And so a potentially brilliant idea goes down the drain.

Untested Prototypes Are Wasteful

The bad consequences do not stop here. Untested code is legacy code. The untested prototype will silently bit-rot either in some online repository or— even worse—just on some department server or backup disk. A few years down the line nobody will remember how to get things working or how to make changes. In other words, the code becomes practically useless. Given the fact that a large part of research is publicly funded, one could consider this a rather direct waste of public money.

Conclusion

To make a long story short: Stop using excuses. Software testing is an essential tool for making sure your research prototype produces correct results. Get familiar with it and use it extensively the next time you develop a prototype. Consider even using test-driven development (TDD) to make sure you test things right from the start.

Now I’m going back to my corner and feel ashamed of all the untested research prototypes I have written!

McConnell, Steve. Code Complete, Microsoft Press, 2004. Page 521. ↩

Blog Comments Using GitHub

2018-10-23T00:00:00+00:00

I’m building this site using Jekyll, the simple, blog-aware, static site generator. While it’s a great tool overall, it comes with a major drawback when it comes to blogging: There’s no out-of-the-box support for comments. Some folks even maintain the view that a blog without comments is not a blog.

I’ve been searching for a reasonable comment system for a while. The most wide-spread solution seems to be to use a third-party service like Disqus. However, this approach is not really an option for me, mostly due to data protection and privacy concerns.

Don Williamson put up a short investigation on how much tracking the use of Disqus involves. Luckily, he directly proposes an enticingly simple solution based on the GitHub issues API:

Each post gets an associated issue on GitHub
Users can leave comments on the post/issue
Some JavaScript pulls the comments from GitHub

The advantages are compelling:

No tracking
Users keep control over their comments
Moderation
Markdown support

There are some obvious drawbacks as well. Users need to:

Leave the site
Have a GitHub account

While this certainly raises the entry burden, it also provides some protection against comment spam. Anyway, I’m gonna give it a try.

Thanks to Dave Compton for providing a Jekyll reference implementation.

The Feynman Problem-Solving Algorithm

2018-10-21T00:00:00+00:00

The Feynman Problem-Solving Algorithm:

Write down the problem
Think real hard
Write down the solution

That’s it. As simple as it gets, yet so difficult.

Rumor has it that this was more of an allusion to Richard Feynman’s legendary problem solving skills. Nevertheless, I find it highly useful for a couple of reasons:

It reminds us that writing down a precise yet comprehensive problem definition is a key step towards a solution. Often enough, this actually is the most difficult part.
The thinking really hard part remains what it is—hard. The good news is: There are some methods and tools to help: George Pólya describes a set of heuristics for solving mathematical problems in his book How to Solve It. Along similar lines, Introduction to the Design and Analysis of Algorithms by Anany Levitin contains an introduction to algorithmic problem solving.
Finally, I consider step 3 as a reminder that formulating the solution requires at least as much care and attention as the previous steps.

Hope this helps.

Practical Test Improvement

2018-10-07T00:00:00+00:00

Time to put some of the unit testing guidelines I described last time into practice. In this post, I’ll go through some concrete examples improving the overall quality of a unit test suite.

The pmp-library will serve as a practical example: Its current test suite is reasonably comprehensive, amounting to a test coverage of around 96%. Most of the tests, however, have been written

in a rush,
without too much thought,
to cover as much code as possible, and
long after the original code was written

Yours truly is partially responsible for that, so it’s only fair enough I spend some time cleaning things up.

Before starting, recall the two fundamental qualities of a unit test:

It runs fast.
It helps to localize problems.

I’ll focus on performance first.

Assessing Performance

We can run the full pmp-library test suite through a simple call to

make test

This reports a run-time of approximately 1.72 seconds on my Dell XPS 13 with a Intel Core i7-7560 CPU running at 2.4 GHz. That’s not too bad, but I’m sure we can do better. We’re currently using Google Test for unit testing. In order to get a more detailed picture, we can run the gtest_runner directly:

cd tests
./gtest_runner

This will report individual run times for each test and test case¹. Skimming through the results quickly reveals the most offending test:

...
[----------] 1 test from PointSetAlgorithmsTest
[ RUN      ] PointSetAlgorithmsTest.smoothing
[       OK ] PointSetAlgorithmsTest.smoothing (1270 ms)
[----------] 1 test from PointSetAlgorithmsTest (1270 ms total)
...

Turns out the biggest time eater right now is the PointSetAlgorithmsTest. This case alone takes up almost 75% of the run time of the entire test suite. The PointSetAlgorithmsTest currently contains only a single test for point set smoothing using iterated Moving Least Squares projection. Given the limited scope of the test it’s hardly justified that it takes up so much of our precious testing time.

Improving Performance

Although it is a bit embarrassing, here’s the PointSetAlgorithmsTest test case in all its glory:

class PointSetAlgorithmsTest : public ::testing::Test
{
public:
    PointSetAlgorithmsTest()
    {
        ps.read("pmp-data/xyz/armadillo_low.xyz");
    }
    PointSet ps;
};

TEST_F(PointSetAlgorithmsTest, smoothing)
{
    Scalar origBounds = ps.bounds().size();
    PointSetSmoothing pss(ps);
    pss.smooth();
    Scalar newBounds = ps.bounds().size();
    EXPECT_LT(newBounds,origBounds);
}

For now I’m ignoring the fact that checking for shrinking model bounds is not really a meaningful test and concentrate on performance instead. The biggest performance impact comes from

using an unnecessarily large model and
loading the model from a file.

This has not only performance implications, but also directly violates two criteria of a good unit test: The test touches the file system and therefore depends on the execution environment. This applies to other cases in the test suite as well, but I’ll stick to this one for now.

A faster and more self-contained way to obtain a test model is to generate a synthetic model on the fly. This also helps to concentrate on a model that is as simple as possible. For this particular case generating a simple unit sphere will be fully sufficient². Here’s a little helper function for doing that:

// Randomly generate nPoints on the unit sphere.
// Stores the resulting points and normals in ps.
void generateRandomSphere(size_t nPoints, PointSet& ps)
{
    ps.clear();

    // normal distribution random number generator
    std::default_random_engine generator;
    std::normal_distribution<double> distribution(0.0, 1.0);

    auto normals = ps.vertexProperty<Normal>("v:normal");

    // generate points and add to point set
    for (size_t i(0); i < nPoints; i++)
    {
        double x = distribution(generator);
        double y = distribution(generator);
        double z = distribution(generator);

        // reject if all zero
        if (x == 0 && y == 0 && z == 0)
        {
            i--;
            continue;
        }

        // normalize
        double mult = 1.0 / sqrt(x * x + y * y + z * z);
        Point p(x, y, z);
        p *= mult;

        // add point and normal
        auto v = ps.addVertex(p);
        normals[v] = p;
    }
}

Using this function to generate the test model and removing the unnecessary test fixture setup leads to a simple and self-contained test:

TEST(PointSetAlgorithmsTest, smoothing)
{
    PointSet ps;
    generateRandomSphere(1000,ps);
    Scalar origBounds = ps.bounds().size();

    PointSetSmoothing pss(ps);
    pss.smooth();

    Scalar newBounds = ps.bounds().size();
    EXPECT_LT(newBounds,origBounds);
}

This change brings down the run-time for this test down to a bare 5ms:

...
[----------] 1 test from PointSetAlgorithmsTest
[ RUN      ] PointSetAlgorithmsTest.smoothing
[       OK ] PointSetAlgorithmsTest.smoothing (5 ms)
[----------] 1 test from PointSetAlgorithmsTest (5 ms total)
...

For the full test suite this change reduces the run time from 1.72s to 0.44s, almost a factor of 4. Good enough for now.

Improving Localization

Originally, I introduced PointSetAlgorithmsTest following the model of its counterpart for surface meshes, SurfaceMeshAlgorithmsTest. The latter contains the tests for all higher level surface mesh processing algorithms in the library. This strategy, obviously, does not provide proper localization, i.e., in case a test fails it is not really straightforward to find out which part of the code is causing trouble.

In retrospect, it would have been more coherent to have separate cases for each of the algorithms under test. After all, the classes and functions implementing the algorithms are our basic units of code.

The PointSetAlgorithmsTest only contains the smoothing test, so this is quickly refactored into PointSetSmoothingTest. In case of SurfaceMeshAlgorithmsTest the situation is slightly more complex because we’ve got more algorithms and scenarios to test. Despite, refactoring the test case is still worth the effort: It not only provides better localization but also provides opportunity to clean up redundant code by using algorithm-specific test fixtures.

To provide a concrete example: All of the curvature computation tests contained the following lines in order to load a mesh of a hemisphere:

mesh.clear();
mesh.read("pmp-data/off/hemisphere.off");
SurfaceCurvature curvature(mesh);
curvature.analyze(1);

Grouping all curvature tests in a SurfaceCurvatureTest case allows to simply use a single test fixture for setup:

class SurfaceCurvatureTest : public ::testing::Test
{
public:
    SurfaceCurvatureTest()
    {
        EXPECT_TRUE(mesh.read("pmp-data/off/hemisphere.off"));
        curvature = new SurfaceCurvature(mesh);
        curvature->analyze(1);
    }

    ~SurfaceCurvatureTest()
    {
        delete curvature;
    }

    SurfaceMesh mesh;
    SurfaceCurvature* curvature;
};

Obviously, the test case still relies on loading data from a file, which is bad, and I’m gonna change it at some point.

Conclusion

By applying some of the basic guidelines for good and clean unit tests the pmp-library test suite now runs as fast as lightning and more properly covers individual units of code.

However, there’s still room for improvement. Especially when it comes to the concepts we are actually testing for I’m far from satisfied with what we’ve got so far.

A whole different problem is how to properly test file I/O and file formats. While there seem to be some strategies out there, I’m not yet sure what’s the right way to go for the pmp-library. In case you have a suggestion, I’d be glad to hear.

Note that Google Test uses a slightly confusing terminology for what is a test, and what is a test case. Basically a test is a single test and a test case is a group of tests. See the Google Test Primer for details. ↩
In a first attempt I used a small sphere point set floating around on my machine. Much to my surprise, this caused the test to fail. Turned out the file had all zero normals, essentially making the algorithm doing nothing. A perfect reminder to harden algorithms against degenerate inputs! ↩

Unit Testing Geometric Algorithms

2018-09-11T00:00:00+00:00

Comprehensive testing is a key aspect of developing high-quality software solutions. In this article, I’ll briefly motivate the use of testing, summarize what makes up a good unit test, and finally dive into some of the challenges when it comes to unit testing geometric algorithms.

The Importance of Testing

Over the last couple of years, extensive software testing has become a cornerstone of high-quality software development. First of all, industrial-strength, production-ready code requires testing in order to make sure the software behaves correctly. Beyond that, having an extensive test suite is the key ingredient to evolve a code base over time as requirements, features, and people working on the code change. As Michael Feathers puts it in his book Working Effectively With Legacy Code: A code base without proper test coverage is legacy code, i.e., a code base that is extremely difficult to work with. There’s practically no way to change the code without risking to break some part of the software’s functionality. Often enough, subtle bugs can be introduced and go unnoticed until the software goes into production—something you definitely want to avoid. In case you’re not yet convinced or you’re all new to software testing, I highly recommend reading Kent Beck’s seminal book Test-Driven Development: By Example.

Note that for the most part of this article, I’ll focus on unit tests, i.e., the type of tests used to assure the correctness of an individual unit of code such as a class or a function. To be more precise, I’m following Michael Feathers’ unit testing rules stating that a test is not a unit test if:

It talks to a database
It communicates across the network
It touches the file system
You have to do special things to your environment to run it.

What Is a Good Unit Test?

Unfortunately, not all tests are created equal. A good test suite allows you to change and evolve your code while assuring correctness. In contrast, a sloppily done test suite can get in your way all too often, thereby significantly slowing down your development speed. While it is trivial to come up with a test, it is much more difficult to come up with a good test. In the extreme case, you could just write one big test function exercising all of your code and simply check for successful execution. Such a test, however, would not fulfill two of the most basic and important characteristics of high-quality unit tests:

They run fast.
They help to localize problems.

Obviously, the one big test function won’t be fast as the code base grows and it won’t help to localize problems due to its monolithic nature. In contrast, a suite of individual test cases that can be run in isolation will allow you to track down problems much faster. Beyond the two basic criteria of speed and localization, a good test suite will exhibit the following properties:

Independent: The tests should not depend on each other. You should be able to run the tests individually and in any order.
Repeatable: The tests should be repeatable and independent of the environment being used.
Self-Validating: Tests should either pass or fail and not require any additional manual inspection.
Timely: Test should be written just before the production code to ensure a testable design.

The excellent book Clean Code from Robert C. Martin contains a full chapter on clean unit tests, and I can only recommend to read it.

Another major aspect is the stability of a test over time. A test that frequently fails upon minor changes is likely to produce lots of false positives. Keeping such a test up-to-date can be a real time sink. Some people refer to such a test as being brittle or flaky. As it turns out, this aspect can be a major challenge when testing geometric algorithms.

Unit Testing Geometric Algorithms

Now, why should unit testing geometric algorithms be any different from other types of algorithms? At a first glance, one might think everything is relatively easy and straightforward. After all, it’s basically just math, so you should be able to calculate the correct outcome of your algorithm, right? Well, this is not quite true. In fact, even for basic operations such as determining whether a point is inside a sphere or not we have to take into account potential floating point precision issues. The folks from the CGAL project made a huge effort in building a library that robustly deals with such precision issues.

Aside from precision issues, for more complex algorithms—such as those encountered in real-world geometry processing tasks—it becomes increasingly difficult to exactly specify what the correct output of an algorithm is. The notion of correctness is no longer as easy to define. Instead, we gradually move to test for acceptable output, i.e., we consider the output to be correct within a certain tolerance. Note the connection to the self-validity criteria mentioned above: Testing for a tolerance does not directly map to a simple pass or fail. Even worse, when we hit the boundaries of the tolerance and the test begins to fail, we eventually need to resort to time-consuming and error-prone manual inspection.

The problem gets aggravated even more when we need to test for multiple tolerances. Let’s consider mesh simplification as an example. For such an algorithm we typically don’t care about individual resulting vertex positions but about more global properties such as the number of resulting triangles as well as deviation from the initial surface. This is, however, not the only criterion we might need to consider. If the resulting mesh is meant to be used in downstream applications for which mesh element quality is relevant—such as finite element simulations—we also need to make sure that the algorithm does not generate degenerate mesh elements. So in this example we eventually need to test for at least three different criteria:

Element count reduction
Distance to the initial surface
Mesh element quality

Obviously, coming up with good default values and tolerances for such an algorithm is not completely straightforward. The next section outlines some strategies and guidelines I found to be useful in the past.

Testing Strategies

So how do we come up with a good test for our geometry processing algorithm? Sorry to disappoint, but there’s not a single definite answer to that. To some extend, this will always require experimentation and previous experience. If you happen to have found the silver bullet for this problem, I’d be glad to hear. In the meantime, however, there are still some guidelines we can follow.

The goal is to have a good and clean test. Recall the localization criterion from above: A good test should help to localize problems. Therefore, it is only natural to concentrate on a single concept per test. An ideal test would only have a couple of lines of code: a setup function, a call to the algorithm, and a set of assertions. Even if you need to test for multiple criteria as in the mesh simplification example above, I recommend to create separate test cases for each of the criteria. Now when writing the test case we basically need to answer three questions:

What exactly is the property I want to test?
What is a reasonable default value?
What is an acceptable tolerance?

By applying the single-concept-per-test strategy you should already have sufficient clarity about the property under test. The only thing you need is some way to compute that property, e.g., a function to compute the minimum element quality in a mesh. Next, to come up with a good default value, I typically start by searching for cases with known outcome. Consider curvature computation as an example. In this case, we know what the curvature should be for certain surfaces such as a plane or a sphere. If there is no such known or obvious case, I tend to think about the minimum viable application scenario of the algorithm and start with the value computed for this case. Finally, unless you already have some knowledge about a reasonable tolerance range, go ahead, vary the input parameters of the algorithm, slightly change the input model, check how sensible the test is to this variation, and adjust the tolerance accordingly.

When you’re done with testing the primary functionality of the algorithm, I recommend not to stop there. Nasty bugs and odd behavior frequently occur for borderline cases. Take some time to think about these and write a test for each one of them. Use a code coverage tool to identify cases not yet covered by your test suite. Finally, it’s always a good practice to make sure your algorithm gracefully handles invalid input. Write a test for it.

Wrapping Up

Time to wrap up, this article already got much longer than expected. In any case, I hope I could somewhat convince you that comprehensive testing is important and that having a high quality test suite will help you to write more clean and robust code in the long run. As for testing geometric algorithms, I hope that the above guidelines will come in handy if you ever need to write a test for a geometry processing algorithm. In case you already have experience in this area, I’d be more than glad to hear any insights or recommendations. Simply drop me a mail.

Markdown Cheat Sheet

2018-09-02T00:00:00+00:00

A minimal Markdown cheat sheet I keep around for reference. Only contains the elements I most frequently use. See John Gruber’s original spec for plain Markdown and this quick reference for kramdown, the default Jekyll Markdown parser.

Element	Syntax
Headings	`# Level 1` `## Level 2` `### Level 3`
Bold	`bold text`
Italic	`_italic text_`
`Monospace`	`monospace text`
Unordered List	`- First Item` `- Second Item` `- Third Item`
Ordered List	`1. First Item` `2. Second Item` `3. Third Item`
Inline Link	`[Link Title](http://url.com)`
Reference Link	`[Link Title][id]` `...` `[id]: http://url.com`
Image	`![alt text](path_to_image.jpg)`
Blockquote	`> quote text`
Fenced Code Block	``` `#include <iostream>` `int main() {}` ```
Tables	`\| Element \| Syntax \|` `\| ------ \| ------------- \|` `\| Item 1 \| Description 1 \|` `\| Item 2 \| Description 2 \|`
Footnote	`Text with a footnote[^1].` `...` `[^1]: The footnote text.`

Heilmeier's Catechism

2018-09-01T00:00:00+00:00

Heilmeier’s Catechism is a set of questions credited to George H. Heilmeier that anyone proposing a research project or product development effort should be able to answer.

What are you trying to do? Articulate your objectives using no jargon.
How is it done today, and what are the limits of current practice?
What’s new in your approach and why do you think it will be successful?
Who cares? If you’re successful, what difference will it make?
What are the risks and the payoffs?
How much will it cost?
How long will it take?
What are the midterm and final “exams” to check for success?

I came across these a couple of times. While there surely is nothing special or extraordinary about them, I still find them highly useful to assess the value and feasibility of a research or development project.

Polishing the pmp-library Documentation

2018-08-26T00:00:00+00:00

High-quality and easily accessible documentation is a key feature of an easy-to-use software library. Since ease of use is a primary design goal of the pmp-library, I recently spent some time polishing up the pmp-library documentation.

We currently use Doxygen to build the full pmp-library.org website, including the user guide and reference documentation. As it stands today, Doxygen is the standard tool for C++ library documentation and comes with a whole bunch of powerful features such as:

Auto-generated API documentation from annotated sources
Support of Markdown pages for higher-level documentation
Automatic cross-linking between pages and reference docs
Proper citation and bibliography handling

That’s all well and good, but Doxygen also comes with a number of drawbacks. In my humble opinion, one of the most significant issues is the poor quality of the generated HTML output. First of all, the default output is rather cluttered, overly verbose, and not exactly clear and concise. There’s a plethora of index pages and menus so that it is not really straightforward to retrieve the information you are searching for. Furthermore, the HTML is not at all suitable for mobile devices. While this might not be too much of an issue for pure API reference docs, in our case this also means the the project homepage and user guide are not really accessible on a wide range of devices.

Being unsatisfied with the current state of affairs, I started to look around for alternative documentation generators. In particular, I investigated Jekyll, MkDocs and Sphinx plus Breathe. However, each of these alternatives comes with its own drawbacks, e.g., lack of auto-generated API docs and automatic cross-references in case of Jekyll and MkDocs, or a rather complicated toolchain in case of Sphinx.

Thus, I decided to see how far I can push a Doxygen-based solution by cleaning up and fine-tuning the HTML output. Checkout the latest version of the pmp-library website for results. I don’t think it is really worthwhile to go through all the modifications in detail. Instead, I’m just providing some pointers to the most important changes:

Disable the overly verbose navigation tabs (DISABLE_INDEX=YES)
Enable the flexible tree view navigation (GENERATE_TREEVIEW=YES)
Use a custom page layout to change the structure of the output
Include custom HTML headers and footers
Customize the CSS to provide a more clean and minimalist appearance
Change the overall color theme to match our logo
Consistently use a few selected fonts

Finally, one particular annoying behavior on mobile devices is the messed up rendering of the split bar separating the tree view and the main content. I ended up modifying the the background image (splitbar.png) used for this component and copying it over using the HTML_EXTRA_FILES tag. Definitely not an elegant solution, but hey, it works for now.

So, even though I’m quite convinced that the customized HTML output represents a significant improvement compared to the standard one, there’s definitely lots of room for further improvement. In case you have any suggestions or spot any issues, please drop me a mail or directly submit an issue.

Glimpse of a Library

2018-01-10T00:00:00+00:00

I’m currently working with the venerable Prof. Botsch on The Polygon Mesh Processing Library, an improved and extended version our Surface_mesh data structure including a more versatile geometry representation as well as a collection of canonical geometry processing algorithms. Highlights include:

Flexible data structures for point sets, edge sets, and surface meshes including dynamic property handling and topological changes.
Implementations of classical geometry processing algorithms such as surface remeshing, simplification, or smoothing.
Visualization utilities based on OpenGL® for rapid prototyping.
A liberal 3-clause BSD license allowing for academic, open-source, and commercial usage.

On top of this, the library can be easily compiled into JavaScript™ using emscripten and can be used to create browser-based applications as demonstrated here.

If you are curious, check out the homepage at www.pmp-library.org and the corresponding GitHub project. Keep in mind, however, there’s no official release yet. Things are still in flux and might change quite a bit. Early feedback is more than welcome. If you’ve got any comments or suggestions, please drop me a mail or submit an issue.

Jekyll Migration

2018-01-09T00:00:00+00:00

I finally took the time to migrate and upgrade my old university homepage something slightly more modern, namely Jekyll. Hope you’ll find what you came here for—if not, let me know.

Daniel Sieger

Connected Components of a Polygon Mesh

Basic Algorithm

C++ Implementation

Testing

Visualization

Filtering

Public Drafts With Jekyll

Publishing Drafts

Building Drafts

Hiding Regular Posts

Custom Collection

Digital Detox

Cutting Social Media

Leaving LinkedIn Behind

Where Attention Goes

Code Coverage with CMake and CTest

A Minimal Setup

Adding Coverage Support

Generating Coverage Information

What’s Next?

Opaque Pointer Pattern in C++

What’s the Problem?

Hiding Behind a Pointer

Opaque Pointer with std::unique_ptr

Advantages

Drawbacks

Wrapping up

Further Reading

PMP Library Version 3.0 Released

API Simplicity

Complex Class Interfaces

Simple Functions

Reducing API Surface

Focus on Singular Use Cases

Don’t Misuse Inheritance

Bottom Line

References and Further Reading

C++ Member Functions vs. Free Functions

An Example

Conclusions

References and Further Reading

A Framework for Better Documentation

Four Types of Documentation

Tutorials

Guides

Reference

Explanation

Wrapping Up

Further Reading

Dieter Rams: Ten Principles for Good Design

Good Design is Innovative

Good Design Makes a Product Useful

Good Design is Aesthetic

Good Design Makes a Product Understandable

Good Design is Unobtrusive

Good Design is Honest

Good Design is Long-Lasting

Good Design is Thorough Down to the Last Detail

Good Design is Environmentally Friendly

Good Design is as Little Design as Possible

C++17 Nested Namespaces

PMP Library Version 2.0 Released

Your Code Doesn't Have to Be a Mess

Define Clear Goals

Setup Constraints

Say No

Eliminate Waste

Minimize Dependencies

Closing Remarks

References and Further Reading

Keep it Simple, Over Time

Code Coverage Testing for C++

What’s Code Coverage?

Why Use Code Coverage?

Getting Started

Generate a HTML Report

CMake Integration

Continuous Integration

Bottom Line

Opaque Pointer with `std::unique_ptr`