Boundary First Flattening

Boundary First Flattening (BFF) is a free and open source application for surface parameterization. Unlike other tools for UV mapping, BFF allows free-form editing of the flattened mesh, providing users direct control over the shape of the flattened domain—rather than being stuck with whatever the software provides. The initial flattening is fully automatic, with distortion mathematically guaranteed to be as low or lower than any other conformal mapping tool. The tool also provides some state-of-the art flattening techniques not available in standard UV mapping software such as cone singularities, which can dramatically reduce area distortion, and seamless maps, which help eliminate artifacts by ensuring identical texture resolution across all cuts. BFF is highly optimized, allowing interactive editing of meshes with millions of triangles.

The BFF application is based on the paper, “Boundary First Flattening” by Rohan Sawhney and Keenan Crane.

View the Project on GitHub

Feature Gallery

  1. Minimal Area Distortion — By default, BFF automatically produces a flattening with minimal area distortion and virtually zero angle distortion. This map is generally useful for most texturing and surface processing tasks.

  2. Direct Editing — The initial map can be edited interactively using handle-based manipulation of the size and orientation of the boundary curve. This can be useful for packing UVs into a texture atlas, or for emphasizing regions of the surface that should receive more texture area (for instance).

  3. Sharp Corners — The domain can also be flattened into a polygon with sharp corners, like a rectangle (useful for, e.g. maximizing use of texture area).

  4. Cone Singularities — Cone singularities can be used to reduce area distortion in regions of high curvature. Cones can be placed manually or automatically, and can be adjusted interactively. Optionally, the resulting map can be made globally seamless along any cuts caused by the placement of cones.

  5. Uniformization — The surface can be mapped to a circular disk (or sphere), which is useful for cross-parameterization (mapping one surface to another).

Download Application

Mac OS X (v1.3)
Windows (v1.1)

Release History

Tutorial

BFF should be fairly intuitive to use, so go ahead and give it a try! If you find you still have questions, the tutorial below may provide some useful guidance. (Warning: As with most tutorials, this one may not be in sync with the latest software version. Read at your own risk! ;-))

BFF can be run either from the command line, which provides automatic parameterization and some basic operations, or in an interactive GUI, which provides additional operations and editing capabilities. Either tool loads a polygon mesh in OBJ format, and produces a flattened mesh (also in OBJ format). Meshes with (and without) boundary, holes, handles and multiple components are supported. The only restriction is that meshes must have manifold connectivity (though this may be relaxed in future versions). Meshes that do not have disk or sphere topology will be automatically cut for flattening.

Overview Video

To get started, take a look at our short (10min.) overview video. More detailed descriptions of individual features are found below.

Interactive Graphical Interface

Initially, the GUI should look something like this:

The 3D View shows the original mesh, the UV view shows the current flattening. Since BFF is incredibly fast, you do not have to take any action to get an updated flattening; the UV view will be automatically refreshed whenever you click on a button or other UI element. The Toolbar provides various options for flattening the surface; pay close attention to the Tool Tips, which can provide useful information about the currently selected tool. By default, the UV map is visualized as a grid on the surface; the shading on the surface is also used to light the UV map, to give a sense of correspondence between 3D and 2D. Additional visualization options are described below. Finally, the Reset button will set the current tool (and the corresponding flattening) back to its default parameters.

New meshes can be loaded by pressing the Load Mesh button; the Export Mesh button allows a mesh to be exported to OBJ format, with the texture coordinates stored in the vt field (one per distinct triangle corner in the flattened mesh). The Export Normalized UVs checkbox will scale the UVs between 0 and 1 in texture space.

Adjusting the View

The view can be independently adjusted in both the 3D view and the UV view. In particular:

Visualization Options

In addition to visualizing the map itself, BFF provides facilities for inspecting the quality of the map. The Shading Menu (first menu in the Plot section) provides the following options:

The Pattern Menu draws different patterns on the surface. These patterns have been chosen to give a sense of the angle and area distortion in the flattening. For a perfect map (i.e., no distortion at all) the pattern should look uniform in scale across the whole surface, and circles and squares in the UV view should look like circles and squares in the 3D view (taking perspective distortion into account). These features will give you a sense of how textures and other data will look when mapped onto the surface. In particular:

The Pattern Scale Slider, found directly below the Pattern Menu, will adjust the scale of the pattern. Such adjustment can be useful for, e.g., understanding what's going on in a map with high area distortion.

The Show Wireframe checkbox toggles display of a wireframe over the mesh edges, which can be helpful for visualizing the map.

Target Boundary

A key functionality provided by BFF is the ability to change the target shape of the flattening, by manipulating its boundary curve. No matter what target shape is used, BFF will tend to reduce a map with very low distortion, so that textures and other data can still be nicely mapped back onto the original surface. Several possibilities are accessible through the graphical interface (and additional possibilities are available through source code-level access):

Cone Singularities

In general, it is impossible to flatten a surface perfectly. Somewhere, there must be distortion of either angles or areas. BFF can produce flattenings with minimal area distortion and virtually zero angle distortion, but in some situations area distortion is still too high for practical use. One solution is to cut the mesh into smaller pieces, each of which is easier to flatten, but typically this is unnecessarily aggressive. One can instead reduce distortion to more reasonable levels by inserting cone singularities, which play much the same role as “darts” in garment design. The BFF GUI makes it easy to explore the effect of placing cones, and also provides the ability to place cones automatically in order to reduce area distortion.

Unlike ordinary cuts, which can cause visual artifacts due to differences in resolution across the cut, BFF guarantees that the map is seamless, meaning that in UV space two corresponding cut edges always have identical length. Seamless maps are discussed in more detail below.

Manual Cone Placement

The easiest way to add cones is simply to click on any point of the surface in either the 3D View or UV View while the target boundary is set to Automatic or Disk. Doing so will insert a cone at the click location, find a cut from this cone to the boundary, and update the flattening. Additional clicks will add additional cones. To see the effect on area distortion, set the plot mode to Area Distortion, which will show the distribution of area distortion over the surface (as described above). Clicking on regions of high area distortion will tend to reduce it. Drawing a pattern (such as grid or checkerboard) will also provide some sense of how much scale distortion remains. Note that a poor choice of cones can actually increase area distortion— some experimentation may be required here. Alternatively, one can try the automatic placement button, as described below. (Cuts are picked automatically in the GUI; the cutting strategy can currently only be changed via source-level modifications to BFF.)

The Angle Control slider allows the cone angle to be adjusted; alternatively, one may type in a specific cone angle (as a multiple of π). The cone angle can be understood in analogy with “darts” in dressmaking: smaller angles will typically accommodate less curvature; large angles are helpful for highly curved regions. For spherical surfaces (with no boundary) the total angle sum must be 4π at all times; the GUI will automatically adjust the least-recently updated cone to make sure this sum holds.

Automatic Cone Placement

A target number of cones can also be placed by simply pressing the Place Cones button. The number of cones can be specified in the # Cones field. Note that computing these cones may take some time, especially for meshes with many boundary vertices. (This feature will be improved in future versions; stay tuned!)

Seamless Maps (Coming soon!)

Placing cones will make cuts in the surface (indicated by red lines). By default, BFF already guarantees that the UV lengths of edges on either side of the cut is guaranteed to be exactly the same, so there is no jump in texture resolution across the cut. Likewise, the angle in UV space between two cut edges is exactly determined by the cone angle—for instance, if all cones angles are a multiple of π/2 (i.e., 90 degrees), then the edges will also be related by 90 degree rotations. To check this, set the drawing pattern to Grid. If all of your cone angles are multiples of π/2, you should see that both the spacing and the direction of grid lines is unchanged as you go across a cut. However, you may also notice that grid lines shift left or right as you cross the cut, resulting in a visible seam. If the surface needs to be covered with a regular pattern (or tessellated into a regular grid), it can be useful to eliminate this seam, which you can do by pressing the Remove Seams button.

Spherical Parameterization

For sphere-like surfaces, BFF will also automatically produce a map to the sphere; simply press the Map to Sphere button. For maps to the sphere, there is less control that can be provided to the user since there is no boundary to edit! (Future versions may expose Möbius degrees of freedom, as with the disk.)

To get a map with lower area distortion, one can again add cone singularities (either automatically or manually) as described above. The surface will automatically be cut into a disk and flattened.

Compiling from source

On Mac OSX and Linux, compiling should be as simple as

git clone https://github.com/GeometryCollective/boundary-first-flattening.git
cd boundary-first-flattening && git submodule update --init --recursive
mkdir build && cd build && cmake ..
make -j 4

These instructions will create a command line and GUI application. The Windows binary shared above was built by linking with the version of OpenBlas included in the deps folder. You will need to include the libopenblas.dll.a static library in your Visual Studio project.

Dependencies

  1. SuiteSparse (instructions to build SuiteSparse on Windows can be found here)
  2. OpenGL (version 4.1 or higher)
  3. OpenGL Mathematics (GLM) (included but not required for command line application)
  4. Nanogui (included but not required for command line application)

Command line interface

The BFF code can be compiled and run independent of the GUI, for easy integration into other software packages / plugins. To run the command line interface, simply navigate into the directory containing the executable bff-command-line and type


./bff-command-line in.obj out.obj
Some optional flags:

Unlike the GUI, the command line application does not expose some of the interactive features of BFF such editing of boundary lengths, corner angles and cone angles. These features can still be accessed via the code level interface (see below).

Code level interface

All features of BFF can be accessed directly through a static library by compiling the code. The most important methods are described in project/include/Bff.h. These methods assume that a standard triangle mesh has already been loaded into the Mesh object, and produce UV coordinates at the corners of each triangle, stored in the uv member of each element of Mesh::corners.


// Computes automatic flattening with minimal area distortion
//    -boundaryData stores either the target angles at boundary vertices (if
//     givenScaleFactors is false) -OR- the target scale factors (if givenScaleFactors
//     is true)
// (resulting flattening is stored in Corner::uv for each corner of this->mesh)
void BFF::flatten(DenseMatrix& boundaryData, bool givenScaleFactors);



// Computes flattening with prescribed cones
//    - the matrix C is just a Vx1 vector of cone angles (usually zero for most vertices)
//    - surfaceHasCut should be set to true if the locations of cones changed
// (resulting flattening is stored in Corner::uv for each corner of this->mesh)
void BFF::flattenWithCones(const DenseMatrix& C, bool surfaceHasNewCut);



// Uniformization over the unit disk
// (resulting flattening is stored in Corner::uv for each corner of this->mesh)
void BFF::flattenToDisk();



// Conformally maps a genus 0 mesh to a sphere
// (resulting flattening is stored in Corner::uv for each corner of this->mesh)
void BFF::mapToSphere();

Author

Rohan Sawhney

Citation

The BFF application implements the algorithm described in the paper:

Boundary First Flattening
Sawhney, Crane
ACM Transactions on Graphics

Our application builds on some terrific insights and work done on conformal flattening in recent years, including the automatic cone placement algorithm found in Ben Chen et al, “Conformal Flattening by Curvature Prescription and Metric Scaling” and the technique used to make maps globally seamless from Springborn et al, “Conformal Equivalence of Triangle Meshes”. We are also indebted to the work of Kharevych et al, “Discrete Conformal Mappings via Circle Patterns”, which introduced the idea of cone singularities into practical conformal parameterization algorithms.

Acknowledgements

Development of this software was funded in part by NSF Award 1717320, and a gift from Autodesk, Inc. Thanks to Tim Davis for help with block reordering and supernodal subfactor extraction in CHOLMOD. Any opinions, findings, and conclusions or recommendations expressed in this material are those of the author(s) and do not necessarily reflect the views of the National Science Foundation.

Awards

BFF is the recipient of the SGP 2019 Outstanding Software Project Award

License

Released under the MIT License