395 lines
16 KiB
HTML
395 lines
16 KiB
HTML
<!DOCTYPE html>
|
|
<html>
|
|
<head>
|
|
<meta charset="utf-8"/>
|
|
<title>libigl</title>
|
|
<meta name="author" content="Alec Jacobson and Daniele Panozzo and others"/>
|
|
<link type="text/css" rel="stylesheet" href="tutorial/style.css"/>
|
|
<script type='text/javascript' src='http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML'></script>
|
|
<link rel='stylesheet' href='http://yandex.st/highlightjs/7.3/styles/default.min.css'>
|
|
<script src='http://yandex.st/highlightjs/7.3/highlight.min.js'></script>
|
|
<script>hljs.initHighlightingOnLoad();</script>
|
|
</head>
|
|
<body>
|
|
|
|
<h1 id="libiglstyleguidelines">Libigl Style Guidelines</h1>
|
|
|
|
<p>Libigl is used and developed by many people. This document highlights some
|
|
style guidelines for <em>developers</em> of the library, but also acts as
|
|
best-practices for users.</p>
|
|
|
|
<h2 id="filefunction">One function, one .h/.cpp pair</h2>
|
|
|
|
<p>The structure of libigl is very flat and function-based. For every
|
|
function/sub-routine, create a single .h and .cpp file. For example, if you have
|
|
a function that determines connected components from a face list <code>F</code> you would
|
|
create the header <code>connected_components.h</code> and <code>connected_components.cpp</code> and the only
|
|
function defined should be <code>void connected_components(const ... F, ... C)</code>. If the
|
|
implementation of <code>connected_components</code> requires a subroutine to compute an
|
|
adjacency matrix then <em>create another pair</em> <code>adjacency_matrix.h</code> and
|
|
<code>adjacency_matrix.cpp</code> with a single function <code>void adjacency_matrix(const ... F, ... A)</code>.</p>
|
|
|
|
<h3 id="example">Example</h3>
|
|
|
|
<p>Here is an example function that would be defined in
|
|
<code>include/igl/example_fun.h</code> and implemented in <code>include/igl/example_fun.cpp</code>.</p>
|
|
|
|
<h4 id="example_fun.h"><code>example_fun.h</code></h4>
|
|
|
|
<pre><code class="cpp">// This file is part of libigl, a simple c++ geometry processing library.
|
|
//
|
|
// Copyright (C) 2015 [Your Name] [your email address]
|
|
//
|
|
// This Source Code Form is subject to the terms of the Mozilla Public License
|
|
// v. 2.0. If a copy of the MPL was not distributed with this file, You can
|
|
// obtain one at http://mozilla.org/MPL/2.0/
|
|
#ifndef IGL_EXAMPLE_FUN_H
|
|
#define IGL_EXAMPLE_FUN_H
|
|
|
|
#include "igl_inline.h"
|
|
|
|
namespace igl
|
|
{
|
|
// This is an example of a function, it takes a templated parameter and
|
|
// shovels it into cout
|
|
//
|
|
// Input:
|
|
// input some input of a Printable type
|
|
// Returns true for the sake of returning something
|
|
template <typename Printable>
|
|
IGL_INLINE bool example_fun(const Printable & input);
|
|
}
|
|
|
|
#ifndef IGL_STATIC_LIBRARY
|
|
# include "example_fun.cpp"
|
|
#endif
|
|
|
|
#endif
|
|
</code></pre>
|
|
|
|
<h4 id="example_fun.cpp"><code>example_fun.cpp</code></h4>
|
|
|
|
<pre><code>// This file is part of libigl, a simple c++ geometry processing library.
|
|
//
|
|
// Copyright (C) 2015 [Your Name] [your email address]
|
|
//
|
|
// This Source Code Form is subject to the terms of the Mozilla Public License
|
|
// v. 2.0. If a copy of the MPL was not distributed with this file, You can
|
|
// obtain one at http://mozilla.org/MPL/2.0/
|
|
#include "igl/example_fun.h"
|
|
#include <iostream>
|
|
|
|
template <typename Printable>
|
|
IGL_INLINE bool igl::example_fun(const Printable & input)
|
|
{
|
|
using namespace std;
|
|
cout<<"example_fun: "<<input<<endl;
|
|
return true;
|
|
}
|
|
|
|
#ifdef IGL_STATIC_LIBRARY
|
|
template bool igl::example_fun<double>(const double& input);
|
|
template bool igl::example_fun<int>(const int& input);
|
|
#endif
|
|
</code></pre>
|
|
|
|
<h3 id="avoidstatichelperfunctions">Avoid static “helper” functions</h3>
|
|
|
|
<p>Strive to encapsulate sub-functions that could possibly be useful outside of
|
|
the implementation of your current function. This might mean abstracting the
|
|
interface a bit. If it doesn’t dramatically effect performance then create a
|
|
new pair of .h/.cpp files with this sub-function.</p>
|
|
|
|
<h4 id="lambdafunctions">Lambda functions</h4>
|
|
|
|
<p>If encapsulation in a separate file is not possible or does not make sense,
|
|
then avoid crowding the namespace by creating lambda functions within the
|
|
function implementation.</p>
|
|
|
|
<p>These lambda functions must still be documented with clear <a href="#headerdocumentation">input and output
|
|
arguments</a>. Avoid using full capturing of all automatic
|
|
variables: do not use <code>[&]</code> or <code>[=]</code>. Rather specify each captured variable
|
|
individually.</p>
|
|
|
|
<h3 id="avoidhelperclasses">Avoid “helper” classes</h3>
|
|
|
|
<p>Libigl is built around the high-performance paradigm of “struct of arrays”
|
|
rather than “array of structs”. The way we achieve this is to avoid classes and
|
|
pass “basic types” directly. The price we pay is long function interfaces, but
|
|
this increases code reuse dramatically. A “basic type” in our context is a
|
|
Eigen type, stl type, or basic C type.</p>
|
|
|
|
<h2 id="headerdocumentation">Header Documentation</h2>
|
|
|
|
<p>Each function prototype should be well documented in its corresponding .h
|
|
header file. A typical documentation consists of four parts:</p>
|
|
|
|
<pre><code class="cpp">// [A human readable description of what the function does.]
|
|
//
|
|
// Inputs:
|
|
// [variable name of first (const) input] [dimensions and description of
|
|
// this input variable]
|
|
// [variable name of second (const) input] [dimensions and description of
|
|
// this input variable]
|
|
// ...
|
|
// Outputs:
|
|
// [variable name of first output ] [dimensions and description of this
|
|
// output variable]
|
|
// [variable name of second output ] [dimensions and description of this
|
|
// output variable]
|
|
// ...
|
|
// Returns [description of return value]
|
|
</code></pre>
|
|
|
|
<h3 id="example">Example</h3>
|
|
|
|
<p>For example the header <code>barycenter.h</code></p>
|
|
|
|
<pre><code>// Computes the barycenter of every simplex
|
|
//
|
|
// Inputs:
|
|
// V #V by dim matrix of vertex coordinates
|
|
// F #F by simplex_size matrix of indices of simplex corners into V
|
|
// Output:
|
|
// BC #F by dim matrix of 3d vertices
|
|
//
|
|
</code></pre>
|
|
|
|
<h2 id="constinputs">Const inputs</h2>
|
|
|
|
<p>All input parameters should be demarcated <code>const</code>. If an input is also an
|
|
output than consider exposing two parameters (one <code>const</code>) or be sure to list
|
|
the variable under both <code>// Inputs:</code> and <code>// Outputs:</code> in the header comments.</p>
|
|
|
|
<h2 id="referenceparameters">Reference parameters</h2>
|
|
|
|
<p>All but simple types should be passed by reference (e.g. <code>Matrix & mat</code>) rather
|
|
than pointers (e.g. <code>Matrix * mat</code>) or value (e.g. <code>Matrix mat</code>).</p>
|
|
|
|
<h2 id="returnsvsoutputparameters">Returns vs output parameters</h2>
|
|
|
|
<p>All functions should be implemented with at least one overload that has a
|
|
<code>void</code> or simple return type (e.g. <code>bool</code> on success/failure). With this
|
|
implementation its then possible to write an overload that returns a single
|
|
output. Please see <a href="#templatingwitheigen">Templating with Eigen</a>.</p>
|
|
|
|
<p>For example:</p>
|
|
|
|
<pre><code class="cpp">template <typename Atype>
|
|
void adjacency_matrix(const ... & F, Eigen::SparseMatrix<AType> & A);
|
|
|
|
template <typename Atype>
|
|
Eigen::SparseMatrix<Atype> adjacency_matrix(const ... & F);
|
|
</code></pre>
|
|
|
|
<h2 id="templatingwitheigen">Templating with Eigen</h2>
|
|
|
|
<p>Functions taking Eigen dense matrices/arrays as inputs and outputs (but <strong>not</strong>
|
|
return arguments), should template on top of <code>Eigen::PlainObjectBase</code>. <strong>Each
|
|
parameter</strong> should be derived using its own template.</p>
|
|
|
|
<p>For example,</p>
|
|
|
|
<pre><code class="cpp">template <typename DerivedV, typename DerivedF, typename DerivedBC>
|
|
void barycenter(
|
|
const Eigen::PlainObjectBase<DerivedV> & V,
|
|
const Eigen::PlainObjectBase<DerivedF> & F,
|
|
const Eigen::PlainObjectBase<DerivedBC> & BC);
|
|
</code></pre>
|
|
|
|
<p>The <code>Derived*</code> template encodes the scalar type (e.g. <code>double</code>, <code>int</code>), the
|
|
number of rows and cols at compile time, and the data storage (Row-major vs.
|
|
column-major). </p>
|
|
|
|
<p>Returning Eigen types is discouraged. In cases where the size and scalar type
|
|
are a fixed <strong>and matching</strong> function of an input <code>Derived*</code> template, then
|
|
return that <code>Derived*</code> type. <strong>Do not</strong> return
|
|
<code>Eigen::PlainObjectBase<...></code> types. For example, this function scales fits a
|
|
given set of points to the unit cube. The return is a new set of vertex
|
|
positions so its type should <em>match</em> that of the input points:</p>
|
|
|
|
<pre><code class="cpp">template <typename DerivedV>
|
|
void DerivedV fit_to_unit_cube(const Eigen::PlainObjectBase<DerivedV> & V);
|
|
</code></pre>
|
|
|
|
<p>To implement this function, it is <strong>required</strong> to implement a more generic
|
|
output-argument version and call that. So a full implementation looks like:</p>
|
|
|
|
<p>In <code>igl/fit_in_unit_cube.h</code>:</p>
|
|
|
|
<pre><code class="cpp">template <typename DerivedV, typename DerivedW>
|
|
void fit_to_unit_cube(
|
|
const Eigen::PlainObjectBase<DerivedV> & V,
|
|
Eigen::PlainObjectBase<DerivedW> & W);
|
|
template <typename DerivedV>
|
|
void DerivedV fit_to_unit_cube(const Eigen::PlainObjectBase<DerivedV> & V);
|
|
</code></pre>
|
|
|
|
<p>In <code>igl/fit_in_unit_cube.cpp</code>:</p>
|
|
|
|
<pre><code>template <typename DerivedV, typename DerivedW>
|
|
void fit_to_unit_cube(
|
|
const Eigen::PlainObjectBase<DerivedV> & V,
|
|
Eigen::PlainObjectBase<DerivedW> & W)
|
|
{
|
|
W = (V.rowwise()-V.colwise().minCoeff()).array() /
|
|
(V.maxCoeff()-V.minCoeff());
|
|
}
|
|
|
|
template <typename DerivedV>
|
|
void DerivedV fit_to_unit_cube(const Eigen::PlainObjectBase<DerivedV> & V)
|
|
{
|
|
DerivedV W;
|
|
fit_to_unit_cube(V,W);
|
|
return W;
|
|
}
|
|
</code></pre>
|
|
|
|
<p>Notice that <code>W</code> is declared as a <code>DerivedV</code> type and <strong>not</strong>
|
|
<code>Eigen::PlainObjectBase<DerivedV></code> type.</p>
|
|
|
|
<p><strong>Note:</strong> Not all functions are suitable for returning Eigen types. For example
|
|
<code>igl::barycenter</code> above outputs a #F by dim list of barycenters. Returning a
|
|
<code>DerivedV</code> type would be inappropriate since the number of rows in <code>DerivedV</code>
|
|
will be #V and may not match the number of rows in <code>DerivedF</code> (#F).</p>
|
|
|
|
<h2 id="functionnamingconventions">Function naming conventions</h2>
|
|
|
|
<p>Functions (and <a href="#filefunction">thus also files</a>) should have simple,
|
|
descriptive names using lowercase letters and underscores between words. Avoid
|
|
unnecessary prefaces. For example, instead of <code>compute_adjacency_matrix</code>,
|
|
<code>construct_adjacency_matrix</code>, <code>extract_adjacency_matrix</code>,
|
|
<code>get_adjacency_matrix</code>, or <code>set_adjacency_matrix</code> just call the function
|
|
<code>adjacency_matrix</code>.</p>
|
|
|
|
<h2 id="variablenamingconventions">Variable naming conventions</h2>
|
|
|
|
<p>Libigl prefers short (even single character) variable names <em>with heavy
|
|
documentation</em> in the comments in the header file or above the declaration of
|
|
the function. When possible use <code>V</code> to mean a list of vertex positions and <code>F</code>
|
|
to mean a list of faces/triangles.</p>
|
|
|
|
<h2 id="classnamingconventions">Class naming conventions</h2>
|
|
|
|
<p>Classes should be avoided. When naming a class use CamelCase (e.g.
|
|
SortableRow.h).</p>
|
|
|
|
<h2 id="enumnamingconvertion">Enum naming convertion</h2>
|
|
|
|
<p>Enums types should be placed in the appropriate <code>igl::</code> namespace and should be
|
|
named in CamelCase (e.g. <code>igl::SolverStatus</code>) and instances should be named in
|
|
ALL_CAPS with underscores between words and prefaced with the name of the enum.
|
|
For example:</p>
|
|
|
|
<pre><code class="cpp">namespace igl
|
|
{
|
|
enum SolverStatus
|
|
{
|
|
// Good
|
|
SOLVER_STATUS_CONVERGED = 0,
|
|
// OK
|
|
SOLVER_STATUS_MAX_ITER = 1,
|
|
// Bad
|
|
SOLVER_STATUS_ERROR = 2,
|
|
NUM_SOLVER_STATUSES = 3,
|
|
};
|
|
};
|
|
</code></pre>
|
|
|
|
<h3 id="exceptionforfileio">Exception for file IO</h3>
|
|
|
|
<p>For legacy reasons, file reading and writing functions use a different naming
|
|
convention. A functions reading a <code>.xyz</code> file should be named <code>readXYZ</code> and a
|
|
function writing <code>.xyz</code> files should be names <code>writeXYZ</code>.</p>
|
|
|
|
<h2 id="usingnamespace...inglobalscope"><code>using namespace ...</code> in global scope</h2>
|
|
|
|
<p>Writing <code>using namespace std;</code>, <code>using namespace Eigen;</code> etc. outside of a
|
|
global scope is strictly forbidden. Place these lines at the top of each
|
|
function instead.</p>
|
|
|
|
<h2 id="namespacesandexternaldependencies">Namespaces and external dependencies</h2>
|
|
|
|
<p>Functions in the main library (directly in <code>include/igl</code>) should only depend on
|
|
Eigen and stl. These functions should have the <code>igl::</code> namespace.</p>
|
|
|
|
<p>Functions with other dependencies should be placed into
|
|
appropriate sub-directories (e.g. if <code>myfunction</code> depends on tetgen then create
|
|
<code>igl/copyleft/tetgen/myfunction.h</code> and <code>igl/copyleft/tetgen/myfunction.cpp</code> and give the function
|
|
the namespace <code>igl::copyleft::tetgen::myfunction</code>.</p>
|
|
|
|
<h3 id="copyleftsubdirectorynamespace">copyleft subdirectory/namespace</h3>
|
|
|
|
<p>Dependencies that require users of libigl to release their projects open source
|
|
(e.g. GPL) are considered aggressively “copyleft” and should be placed in the
|
|
<code>include/igl/copyleft/</code> sub-directory and <code>igl::copyleft::</code> namespace.</p>
|
|
|
|
<h2 id="assertions">Assertions</h2>
|
|
|
|
<p>Be generous with assertions and always identify the assertion with strings:</p>
|
|
|
|
<pre><code class="cpp">assert(m < n && "m must be less than n");
|
|
</code></pre>
|
|
|
|
<h2 id="ifndefincludeguard">ifndef include guard</h2>
|
|
|
|
<p>Every header file should be wrapped in an <code>#ifndef</code> compiler directive. The
|
|
name of the guard should be in direct correspondence with the path of the .h
|
|
file. For example, <code>include/igl/copyleft/tetgen/tetrahedralize.h</code> should be</p>
|
|
|
|
<pre><code class="cpp">#ifndef IGL_COPYLEFT_TETGEN_TETRAHEDRALIZE_H
|
|
#define IGL_COPYLEFT_TETGEN_TETRAHEDRALIZE_H
|
|
...
|
|
#endif
|
|
</code></pre>
|
|
|
|
<h2 id="spacesvs.tabsindentation">Spaces vs. tabs indentation</h2>
|
|
|
|
<p>Do not use tabs. Use 2 spaces for each indentation level.</p>
|
|
|
|
<h2 id="maxlinelength">Max line length</h2>
|
|
|
|
<p>Limit lines to 80 characters. Break up long lines into many operations (this
|
|
also helps performance).</p>
|
|
|
|
<h2 id="includeorder">Include order</h2>
|
|
|
|
<p><code>#include</code> directives at the top of a .h or .cpp file should be sorted
|
|
according to a simple principle: place headers of files most likely to be
|
|
edited by you first. This means for
|
|
<code>include/igl/copyleft/tetgen/tetrahedralize.cpp</code> you might see</p>
|
|
|
|
<pre><code class="cpp">// [Includes of headers in this directory]
|
|
#include "tetrahedralize.h"
|
|
#include "mesh_to_tetgenio.h"
|
|
#include "tetgenio_to_tetmesh.h"
|
|
// [Includes of headers in this project]
|
|
#include "../../matrix_to_list.h"
|
|
#include "../../list_to_matrix.h"
|
|
#include "../../boundary_facets.h"
|
|
// [Includes of headers of related projects]
|
|
#include <Eigen/Core>
|
|
// [Includes of headers of standard libraries]
|
|
#include <cassert>
|
|
#include <iostream>
|
|
</code></pre>
|
|
|
|
<h2 id="placementofincludes">Placement of includes</h2>
|
|
|
|
<p>Whenever possible <code>#include</code> directives should be placed in the <code>.cpp</code>
|
|
implementation file rather than the <code>.h</code> header file.</p>
|
|
|
|
<h2 id="warnings">Warnings</h2>
|
|
|
|
<p>Code should compile without firing any warnings.</p>
|
|
|
|
<h3 id="anexception">An Exception</h3>
|
|
|
|
<p>The only exception is for the use of the deprecated
|
|
<code>Eigen::DynamicSparseMatrix</code> in core sub-routines (e.g. <code>igl::cat</code>). This class
|
|
is still supported and faster than the standard, non-deprecated Eigen
|
|
implementation so we’re keeping it as long as possible and profitable.</p>
|
|
|
|
</body>
|
|
</html>
|