Boundary First Flattening (BFF)

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

Features

1. Automatic parameterization with minimal area distortion. This map is generated by default when the application is launched.

2. Direct manipulation of boundary lengths or angles of the flattened domain with a spline based curve editor.

3. Exact preservation of sharp corners for flattened domains like rectangles.

4. Seamless cone parameterization. This is a powerful technique for mitigating area distortion that first maps to a cone surface, which is flat everywhere except at a collection of isolated points. After cutting through these points, the cone surface is flattened into the plane without further distortion. Users can pick cones manually or use a built in algorithm to pick them automatically. Cutting is automatic.

5. Mapping to a unit disk for surfaces with boundary.

6. Mapping to a unit sphere for sphere like surfaces.

Download Application

Mac OSX v1.5

Windows v1.5

Release History

• v1.0 (December 2017) — Initial release.
• v1.1 (January 2019) — Adds support for arbitrary topology (holes, handles, etc.; not just disk and sphere), quad and polygon meshes, command-line interface with no GUI build dependencies, and 3x overall speedup across load/solve/write operations.
• v1.2 (June 2019) — Ensures that vertex ordering in the input/output meshes agree; accelerates cone computation for surfaces with boundary; minor accelerations and bug fixes.
• v1.3 (August 2019) — Adds support for tighter bin packing; ensures vertex ordering is preserved; more error logging and bug fixes.
• v1.4 (June 2020) — Improved spherical parameterization; bin packing related bugfixes and more efficient loading of models with many components.
• v1.5 (March 2023) — Updated dependencies; restructured project to avoid include conflict; option to export UVs as mesh positions in OBJ file.
• v1.6 (May 2023) — Support for non-manifold geometry; increased robustness to low quality triangulations; improved hole filling, packing efficiency and GUI load times; USD support.

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 or USD format, and produces a flattened mesh (also in OBJ or USD format). Meshes with (and without) boundary, holes, handles, multiple components and non-manifold connectivity are supported. Meshes that do not have disk or sphere topology will be automatically cut for flattening.

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

Adjusting the View

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

• rotate — click and drag on any point in the background (not on the mesh)
• translate — alt/option-click on the background
• zoom in/out — scroll up/down

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:

• Constant — no special shading; useful for looking at the wireframe or checking for local overlaps. In this view, flipped triangles (which are fairly rare) will be drawn in bright red.
• Shaded — the mesh in the UV view will be lit using the shading from the 3D view. This shading gives a quick way to see which features get mapped where.
• Conformal Distortion — shows angle distortion in the mapping. Blue means no angle distortion, green means a little angle distortion, and red means a lot of angle distortion. For reasonably nice meshes (e.g., smallish triangles, not too crazy aspect ratios) you should see very little angle distortion. Large angle distortion on simple models may indicate that there is something wrong with your mesh (e.g., long invisible slivers or near-degenerate elements). In this mode, the total angle distortion will be printed out above the Shading Menu (this quantity is the average and maximum quasi conformal distortion, where 1 means no distortion).
• Area Distortion — shows how much area is distorted by the mapping. White means no area distortion, blue means shrinking, and red means expansion. In this mode, the total area distortion will be printed out above the Shading Menu (this quantity is the average and maximum log conformal factor, where zero means no distortion).

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:

• None — no pattern is displayed. Useful for getting a clear view of other features of the map (e.g., area distortion, or the wireframe).
• Grid — draws a regular grid pattern. (Note that for maps with cones or cuts, grid lines will line up exactly only if the map is made seamless.)
• Checkerboard — draws a regular checkerboard pattern. (Note that even for seamless maps there may be a jump from black to white, due to parity considerations.)
• Circles — draws random circles. For a map with low angle distortion, these circles should still look like circles (rather than ellipses) on the 3D surface.

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

• Automatic — if no special control over the boundary is required, BFF automatically produces the flattening with minimal area distortion. (Note that since we mathematically guarantee that this is the lowest area distortion, it is not possible to reduce area distortion by using different flattening software. However, area distortion can be reduced by adding cuts and cone singularities; see below.)
• Disk — maps the surface to a circular disk. This map provides an easy way to get a map between two different surfaces (e.g., two different faces): just map each surface to the disk independently, then to locate a point in the 2nd mesh corresponding to a given point on the 1st mesh, follow the maps from the 1st surface, to the disk, and then back to the 2nd surface. (Expert comment: there are Möbius degrees of freedom that are not exposed by the GUI; direct control over these degrees of freedom may be supported in a future release.)
• Edit Boundary — provides direct manipulation of the boundary curve using a user-specified spline. Control points can be added (or removed) by clicking (or ctrl-clicking) points on the boundary. Clicking and dragging on a handle will change the scale; holding shift will control the angle instead of the scale.
• Set Boundary Angles — allows the corner angles of a polygon to be specified. Angles can be specified using the Angle Control slider, or by typing in the angle box (where the value is interpreted as a multiple of π). As with any polygon, these angles must of course sum to 2π— the GUI will automatically adjust the angles to preserve this sum at all times, by adjusting the angle at the corner that was least-recently updated.

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.

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 patte