Extensions:2.6/Py/Scripts/Import-Export/Paper Model

From BlenderWiki

Purpose

This script generates a flat net of a given mesh. It creates SVG files suitable for direct printing and paper modeling. The main goal is a maximal possible automation of the whole process. Common tasks like baking model's texture onto the output are also offered by the UI.

Installation

• Download the file directly from the Git repository
• Launch Blender. In User Preferences (CtrlAltU), section Addons, click the Install Addon button below. Choose the file you downloaded. Then find an addon called Import-Export: Export Paper Model and enable it.

Usage

Select the mesh you want to export so that it is the active one. If you want to get results quickly, just execute this script from the File->Export menu (or find the Export Paper Model operator in the Space menu). It will ask for a file name and do everything else automatically. All needed settings are in the bottom left corner. These are described in more detail below.

If you are somehow unhappy with the generated net, you can edit it manually. For this, you have to execute the Make Unfoldable operator first. Edges that will be cut in order to flatten the mesh must be marked as edit mode seams. You can use Clear Seam and Mark Seam tools to organize them as you wish. If you export the model afterwards, it will take the given seams and add some more cuts as needed.

You can call the Make Unfoldable operator just to have a preview of the net. It will list all islands of the produced net in 3d View T toolbox and (if there was an UV slot available) create an UV layout showing the islands. Note that island positions are not calculated, so these will just lay on top of each other. You can use the Pack Islands operator to see them all.

N-gon faces that are not flat will not get exported correctly and may distort the whole net. You will not be warned about that (except for a messy message in the console), so if you have a suspicion, better convert the mesh to triangles (CtrlT).

Available Settings

3d View Toolbox

The Paper Model tab in the toolbox offers two buttons for calling the Make Unfoldable and Export Paper Model operators conveniently.

Once the Make Unfoldable operator is called, the model is split into islands and these are presented in a list between the two buttons. The list allows you to change the label of each island, which has currently no effect (but will in the future).

If you select an island and enable the Highlight Selected Island button (and the mesh you unfolded is the active one), the island will be highlighted in orange in the 3d View. By a slider below, you can change the highlighting opacity.

Make Unfoldable Operator

The operator has only three settings, which all adjust edge cutting priority (namely: Face Angle Convex, Face Angle Concave, Edge Length). A high value gives an edge with the corresponding property more chance to be cut. Because of that, it is usually better to set Edge Length to a negative value, letting long edges stay connected. For more information about these, read the How It Works → Make Unfoldable part of this document.

Export Paper Model

When the export is initiated, the script silently unfolds the mesh (without making any seams) and creates islands of faces. Then, a file select window is displayed. The file name you choose will get a "_page<number>.svg" suffix, even if only one page was needed. If images are needed, they are saved under the same name with an extension ".png".

Settings of this operator are presented in the bottom left corner of the file select window. First two simply define the page size, default is European A4. The third is DPI, which defines the overall resolution of the net: not only resolution of baked images (if any), but also line thickness.

Model Scale can be used to scale the whole net. It is very important because currently the script often produces islands bigger than the page. By default, it is set so that even the biggest island fits the page size. If set to one, the real model should have the same dimensions as the virtual one.

Pure Net is by default enabled and it creates a black net on white background. If you uncheck it, the model will be baked (full render) and these baked images will be used as background for the net. If Pure Net is enabled, the island layout on pages can be easily changed in a vector editor; if disabled, it is very hard to do. Bake Selected to Active is just the same switch as in Render Properties, but with only temporary effect.

Tab Size sets maximal width of the sticking tabs around islands. The actual size of each tab is adjusted to be at most half the length of the corresponding edge. In some special cases, tabs are made not to overlap with real faces, but it does not work dependably.

Line Thickness defines line width in pixels, so that the width in real units is line_thickness / DPI. If it is set to 1, all folding lines will be 1 pixel in width, and outer lines will be 1.5 px with a 2 px outline to give more contrast from background image (Pure Net does not have this outline).

Development

Feature requests, bug reports and all other constructive comments are most welcome. A publicly accessible TODO list is managed along with the git repository. Or if you prefer so, you may comment on the script at Blenderartists.org thread.

The bug or feature I'm currently working on is set in the nearest plan milestone in the issue tracker.

How It Works

Make Unfoldable

Firstly, the algorithm assigns every edge a "priority", depending on its angle and length. Edges with higher priority will more probably be cut apart in the final net. Shorter edges have higher priority (they are easier to glue on) and sharper angles too (that makes the net easier to understand).

Faces form a concave angle if their normals are pointing against each other. Such angles have even a bit higher priority, because they need to be cut in many typical models. If face normals are flipped, the algorithm thinks their angle is always convex (as there is no way to tell until the whole net is produced).

If more than two faces are connected by an edge, two of them are chosen arbitrarily as the main ones and all others will have to be glued.

The actual priority effect of each of these properties may change the resulting net very much. The default values were chosen as good for common models, but may be a bad choice for others. If you want to tweak them, the Make Unfoldable operator allows you to: they are the operator's three only settings.

The cutting algorithm begins with all faces separated and tries to connect them to form bigger islands, ordered by the connecting edge's priority. If some of the faces of the resulting island would overlap, the operation is canceled and the algorithm continues with another edge. The process stops as soon as all edges of the mesh have been visited.

The overlap check is basically Bentley-Ottmann algorithm for line segment intersection. It is reliable and quick, but does not detect face overlaps that do not consist of any lines crossing each other. Such cases are fortunately extremely rare, but have to be fixed manually if they occur (it may happen to geometrically precise and at least partially concave solids).

Positioning the Nets on Pages

Because the nets are not consisting only of the real faces, but also of the gluing tabs around, they cannot be positioned by the internal Blender operator (Pack Islands). Therefore, a stand-alone algorithm had to be written.

For a great simplification of the process, all nets are packed into (smallest possible) bounding rectangles. These are then ordered by size (largest first) and in this order they are tried to be placed on a page. When any of them is placed, a buffer of free space (also saved as rectangles) is updated: the used one gets removed, two new rectangles are added and all others that overlap with the new net are cut off (see images 1b, 1c below). The free space cache is used to determine quickly whether a given rectangle can be placed on the page.

When there are any rectangles left that could not be placed onto the page, a new free page is created.

Polygon packing is a very difficult problem and no simple and good algorithm is yet known. However, the one used is really stupid. One of its problems that could be solved is that "free space rectangles" that have the left-lower corner flowing in free space will not be recognized at all (see images 2a, 2b). Unfortunately, these are often the biggest rectangles on the page.

1a - 1c: First nets are placed on a page, free space marked as dashed rectangles.
2a, 2b: Although much free space is detected, the biggest rectangle remains often unseen.